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内 容 提 要 
本 书 来 自 真正 的 开发 现场 ， 是 BePROUD 公司 众多 极 客 在 真实 项 目 中 的 经 验 总 结 和 智慧 结 蝇 。 
作者 从 Python 的 环境 搭建 开始 讲 起 ， 介 绍 了 We 应 用 的 开发 方法 、 项 目 管 理 及 审查 、 测 试 与 高 效 
部 署 、 服 务 器 调试 等 内 容 ， 尽 可 能 网 罗 了 Python 项 目 开 发 流程 中 的 方方面面 ， 有 助 于 开发 者 建立 
有 序 生产 环境 ， 提 高 开发 效率 ， 让 编程 事半功倍 。 此 外 ， 在 本 书 中 Python 仅仅 是 一 个 载体 ， 很 多 
知识 点 在 非 Python 下 也 适用 。 
本 书 适 合 有 一 定 基 础 的 Python 开发 者 ， 以 及 使 用 PHP 或 Ruby 进行 开发 的 读者 阅读 。 
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LENIE, BePROUD 公司 已 使 用 Python 开发 了 诸多 项 目 。 我 们 之 所 以 撰写 本 书 ， 是 为 了 
与 各 位 谈 者 分 孚 我 们 在 实践 中 总 结 出 的 一 些 技巧 。 

同时 ， 鉴 于 最 近 公 司 员 工 数量 增长 ， 我 们 把 在 BePROUD 工作 所 需 的 知识 也 写 和 人 了 本 书 ， 
以 便 新 的 公司 成 员 能 尽快 熟悉 工作 。 

因此 本 书 从 搭建 工作 环境 开始 讲 起 ， 逐 步 涉 及 Web 应 用 的 开发 、 项 目 管理 及 审查 、 测 试 代 
但 的 编写 与 高 效 部 署 、 服 务 需 调试 等 方面 ， 网 多 了 Python 项 目 开 发 工作 中 的 一 系列 流程 。 书 名 
中 的 “实战 ”一 词 就 包含 了 “工作 ”的 意思 。 

书 中 所 写 的 技巧 主要 源 于 我 们 的 Python 开发 经 验 。 也 正 因 为 如 此 ， 本 书 将 以 Python2 为 例 
进行 讲解 。 如 今 新 的 开发 项 目 已 经 在 使 用 Python3 ， 这 些 技巧 转移 到 Python3 上 理应 同样 适用 。 

进入 正题 之 前 ， 先 来 聊 聊 我 们 的 日 帝 思 路 。 














e 极 客 / 书 虫 常 伴 身边 的 公司 
BePROUD 里 不 乏 极 客 和 书 虫 们 。 在 这 里 ， 很 多 人 对 特定 领域 的 了 解 程度 能 吓 掉 你 的 下 巴 。 
在 这 里 ， 人 们 一 旦 发 现 感 兴趣 的 事 ， 就 会 拿 出 私人 时 间 来 学 习 、 实 践 。 要 知道 ， 极 客 和 书 
虫 们 不 会 为 这 种 事情 音 青 时 间 。 
正如 人 们 印象 中 的 那样 ， 极 客 和 书 虫 们 大 多 有 些 怪癖 ， 但 BePROUD 的 员工 都 具备 下 列 共识 。 











@ 希望 能 不 做 不 想 做 的 事 

在 工作 中 ,重复 单调 的 作业 是 一 种 极其 无 趣 的 事 ， 因 此 能 一 次 办 完 的 事 谁 都 不 想 去 办 两 次 。 
另外 ， 大 家 也 都 讨厌 工序 复杂 、 容 易 出 错 的 工作 。 所 以 要 开动 脑筋 ， 把 复杂 的 工序 简单 化 ， 同 
时 尽量 减少 出 错 的 机 会 。 








@ 希望 学 会 好 的 方法 并 付 诸 实 器 
世界 上 有 许多 公认 的 好 方法 、 新 思路 和 新 技巧 ， 我 们 要 勇于 尝试 ， 学 习 它 们 并 付 诸 实践 。 








使 用 好 的 方法 必然 能 帮助 我 们 削减 不 想 做 的 工作 。 不 过 ， 方 法 的 好 坏 不 能 人 云 亦 云 ， 我 们 
必须 选 出 对 目 己 真正 有 必 助 的 方法 ， 然 后 再 将 所 学 方法 应 用 到 实际 业务 当中 。 





© 希望 工作 时 有 个 好 心情 

现在 ， 我 们 学 会 了 优秀 的 方法 、 削 减 了 繁杂 的 工作 ， 之 后 自然 希望 带 着 好 心情 去 工作 。 此 
时 不 妨 给 Skype 做 个 好 玩 的 bot，, 或 者 在 下 班 后 找 个 会 议 室 搞 一 场 妙趣 横生 的 快速 演讲 。 我 们 希 
望 大 家 能 在 保质 保 量 完成 工作 的 同时 有 个 好 心情 ， 而 不 是 只 把 公司 当 作 工 作 的 场所 。 这 是 我 们 
的 理念 。 




















本 书 的 内 容 全 部 基于 事实 ， 都 是 BePROUD 员工 实际 尝试 、 实 践 过 的 。 我 们 希望 给 各 位 提 
供 一 些 能 实际 应 用 日 行 之 有 效 的 知识 ， 而 不 是 让 各 位 去 死记 硬 缘 一 大 堆 星 淮 难 懂 的 概念 。 我 们 
很 愿意 看 到 本 书 的 知识 能 对 各 位 有 所 帮助 ， 愿 各 位 能 在 工作 中 有 个 好 心情 。 
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Tic] RE e DL Be TEE Mb BePROUD 员工 。 如 果 没 有 各 位 员工 长 期 以 来 的 切磋 琢 
磨 ， 这 本 书 永远 不 会 问世 。 

至 此 , 希望 这 本 集 诸 人 之 力 编撰 出 来 的 书 ， 能 为 IT 业界 出 一 份 绢 注 之 力 。 

















全 体 执笔 者 
2015 年 1 月 





O 木 书 网 址 


http://www.ituring.com.cn/book/1719 


C 本 书 介绍 的 软件 版 本 和 URL 均 为 截止 到 2015 年 1 月 底 的 最 新 信息 ， 当 前 可 能 已 发 生变 更 。 
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e 本 书 涉及 的 内 容 

本 书 分 为 4 个 部 分 ， 共 15 章 。 

第 1 部 分 “Python 开发 人 门 ” 的 重点 将 放 在 个 人 开发 。 内 容 涵盖 Python 开发 过 程 中 必 不 可 
少 的 工具 的 安装 (第 1 章 )， 简单 的 Web 应 用 开发 (第 2 章 ) 以 及 Python 项 目的 结构 与 包 的 创 
建 (第 3 章 )。 

第 2 部 分 “团队 开发 的 周期 ”将 为 各 位 说 明 多 人 团队 开发 的 相关 问题 。 这 部 分 将 重点 介绍 
团队 高 效 开 发 过 程 中 不 可 或 缺 的 技术 和 技巧 ， 内 容 涵盖 团队 开发 前 的 环境 调整 (第 4 草 )、 项 目 
管理 与 审查 (第 $ 章 )、 源 但 管理 (第 6 章 ) 作 文档 (第 7 章 )、 模 块 设计 与 单元 测试 (第 8 章 小 
封装 及 其 运用 ( 第 9 草 )、 持 续集 成 (第 10 草 ) 等 。 

第 3 部 分 “服务 公开 ”将 加 各 位 讲解 如 何 搭 建 与 运用 正式 环境 公开 Web 服务 (第 11 章 )， 
此 外 就 是 有 关 性 能 调 市 的 一 些 方法 (第 12 3€). 

第 4 部 分 “加 速 开发 的 技巧 ”可 以 说 是 加 速 开 发 的 一 些小 贴 士 。 例 如 将 测试 的 概念 导入 整 
个 开发 流程 以 加 快 项 目 进 度 (第 13 3€ ), Django 的 基础 及 其 进 阶 性 、 实 践 性 的 用 法 C98 14 3$ ), 
Python 的 辅助 模块 (第 15 3€ ) 等 。 























@ 阅读 本 书 前 的 准备 
环境 及 版 本 
e OS: Ubuntu-14.04 
e Python: 2.7.6 
e Bash: 4.3 
e 从 第 2 章 起 ， 如 无 特别 说 明 ， 则 运行 环境 此 由 virtualenv 搭建 。 
关于 OS 
实体 机 使 用 Windows/OS X/Linux， 服 务 融 的 测试 环境 使 用 虚拟 机 上 的 Ubuntu. 
Python 的 官方 手册 
https://docs.python.org/2.7/ 


我 们 仅 对 Python 官方 手册 中 的 内 容 做 最 低 限 度 的 介绍 ， 部 分 说 明 会 被 省 略 。 因 此 建议 各 位 
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手边 时 常 准 备 一 份 参考 手册 以 便 阅 读 。 

Python 的 官方 教程 非常 适用 于 学 习 Python 的 基本 安装 流程 、 语 法 、 术 语 、 类 以 及 模块 。 本 
书 将 以 各 位 看 过 这 份 教程 为 前 提 进 行 讲 解 。 
Unix/Linux 的 一 般 命 令 操 作 

本 书 虽 以 Ubuntu Linux 为 前 提 讲 解 ， 但 书 中 不 对 Ubuntu Linux 的 基本 命令 操作 进行 说 明 。 
天 于 PyPI ( Python Package Index ) 

是 一 个 集中 管理 包 的 网 站 ，pip 等 目 动 包 安装 工具 会 用 到 它 。 本 书 使 用 的 包 也 来 和 月 PyPI。 

天 于 敏捷 过 程 与 极限 编程 

本 书 并 不 对 敏捷 过 程 ( Agile Process ) 和 极限 编程 ( ExtremeProgramming ) 做 单独 的 说 明 。 
如 今 在 许多 书籍 和 网 站 上 都 能 找到 这 二 者 的 介绍 ， 感 兴趣 的 读者 可 以 去 读 一 读 。 
本 书面 向 的 人 群 

e 希望 改善 个 人 开发 环境 的 人 

e 希望 改善 团队 开发 的 人 

e 想 学 习 工作 中 可 使 用 的 Python 技巧 的 人 

。 新 加 入 BePROUD 公司 项 目的 成 员 

















PyPI” 





























e 注意 
e 本 书 基于 作者 本 人 的 调查 结 采 而 成 。 
e 我 们 在 加 工本 书 时 力求 完美 。 不 过 奉 您 发 现 本 书 存 在 不 足 和 错误 、 漏 记 等 问题 ， 请 书面 联系 出 版 方 。 
e 对 于 因 本 书 内 容 运用 不 当 而 导致 的 结 采 及 其 影响 ， 无 论 是 否 因 上 述 两 项 内 容 引 起 ， 我 们 均 不 负责 ， 请 知悉 。 
e 未 获得 出 版 方 书面 许可 不 得 全 部 或 部 分 复制 本 书 。 


@ 商标 等 


本 书 已 省 略 “@ © 等 符号 。 

Python 徽标 是 the Python Software Foundation 的 商标 。 

Django 和 Django 徽标 是 Django Software Foundation 的 商标 。 
Google App Engine 是 Google Inc. 的 商标 。 

Jenkins 是 SOFTWARE IN PUBLIC INTEREST, INC. 的 商标 。 
nginx 是 Nginx Software Inc. 的 商标 。 

VirtualBox 是 ORACLE AMERICA, INC. 的 商标 。 

Ubuntu 是 Canonical Limited 的 商标 。 

此 外 ， 公 司 名 和 商品 名 、 系 统 名 一 般 为 各 开发 者 的 注册 商标 。 
本 书 注册 商标 中 还 使 用 了 普 这 使 用 的 通用 和 名。 








(D nttps://pypi.python.org/pypi 
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在 第 1 部 分 中 ,我们 将 搭建 Python 的 基本 环境 ， 并 进行 简单 的 Web 应 用 开 
发 。 然 后 根据 已 开发 出 的 Web 应 用 进一步 优化 环境 ， 继 续 开发 流程 ， 直 至 其 可 
以 公开 给 一 般 用 户 使 用 。 
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P2% 开发 Web 应 用 
第 3 章 Python 项 目的 结构 与 包 的 创建 
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各 位 在 学 习 新 技术 或 新 编程 语言 时 ， 是 否 对 准备 工作 发 过 愁 呢 ?” 往 往 学 习 还 没有 正式 开始 ， 
就 先 在 准备 工作 上 迷失 了 方向 。 好 不 容易 硬 着 头皮 开始 准备 ， 却 发 现 安装 完 一 个 软件 之 后 又 不 
知道 该 干什么 了 。 最 后 自 以 为 准 备 完 毕 兴 冲冲 地 要 开工 时 ， 才 注意 到 应 该 装 好 的 东西 并 没有 正 
确 安装 。 到 头 来 ， 大 把 的 时 间 花 在 了 准备 阶段 上 ， 再 无 心情 去 学 习 了 。 类 似 这 种 情况 不 知道 各 
位 遇 到 过 没有 。 

搭建 Python 开发 环境 时 要 考虑 OS 与 版 本 等 诸多 组 合 ， 所 以 这 个 过 程 很 难保 证 一 帆 风 顺 。 
独立 开发 者 ， 尤 其 是 自学 成 才 的 开发 者 们 ， 大 多 是 以 网 页 或 书籍 上 的 信息 作为 参考 ， 然 后 用 自 
己 独 有 的 方法 进行 搭建 。 但 即便 如 此 ， 其 中 有 些 共通 点 还 是 需要 了 解 的 。 

第 1 章 中 ,我 们 将 按部就班 地 了 解 对 个 人 开发 者 来 说 共通 的 环境 搭建 顺序 ， 让 初学 者 也 能 
顺利 搭建 环境 。 

因此 ， 我 们 将 在 第 1 章 中 对 下 列 项 目 进行 重点 学 习 。 其 中 有 部 分 内 容 涉 及 虚拟 机 ， 所 以 我 
们 将 学 习 时 使 用 的 本 地 实体 机 的 OS 称 为 “ 主 O0S”， 虚 拟 机 的 OS 称 为 “ 客 0S"。 已 经 自己 搭建 
好 Python 开发 环境 的 读者 可 以 跳 过 本 章 。 









































e 4X Python 
e 安装 Mercurial 


e 天 于 编辑 条 以 及 开发 辅助 工具 


1.1 XX Python 


ZK- prp ee zx eE TE Ubuntu 上 使 用 Python 进行 开发 的 工具 和 包 。 


NOTE 

本 书 以 Upuntu 14.04 ( Server 版 ) 作为 Python 开发 环境 的 OS。 另 外 ， 我 们 使 用 
OracleVMVirtualBox 承载 客 OS。 搭 建 环境 的 相关 内 容 收 录 在 附录 A 以 及 附录 B 中 ， 初 学 者 请 
先 参考 附录 再 阅读 以 下 内 容 。 
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m 
1.1.1 安装 deb & 
Ubuntu 可 以 用 apt-get 命令 管理 包 。 我 们 和 来 更 新 所 有 包 ， 同 时 安 交 一 些 Python 开发 所 
ra HL 
加 LIST 1.1 deb 包 的 更 新 、 升 级 
$ sudo apt-get -y update 
$ sudo apt-get -y upgrade 
$ sudo apt-get -y install build-essential 
$ sudo apt-get -y install libsqlite3-dev 
$ sudo apt-get -y install libreadline6-dev 
$ sudo apt-get -y install libgdbm-dev 
$ sudo apt-get -y install zliblg-dev 
$ sudo apt-get -y install libbz2-dev 
$ sudo apt-get -y install sqlite3 
$ sudo apt-get -y install tk-dev 
$ sudo apt-get -y install zip 
$ sudo apt-get -y install libssl-dev 
如 LIST 1.1 所 示 ， 我 们 在 执行 命令 时 添加 了 -y 选 项 。 这 样 一 来 ， 在 安 儿 过 程 中 被 询问 Yes 


或 No 时 ， 

build-essential 包 可 以 批量 安装 Python 在 Ubuntu 上 进行 构建 时 dii 需 的 全 部 工具 
等 )。Python 本 身 在 涉及 某 些 包 和 模块 时 也 必 胜 
ACHT. 


计算 机 会 自动 帮 我 们 选择 Yes。 Ine fH 逐个 确认 ， 可 以 将 -y 选项 删 去 。 








(gcc、make 





页 有 这 些 基 本 工具 才能 进行 安装 ， 因 此 建议 各 位 先 


接 下 来 安 竣 Python 相关 的 包 (LIST 1.2 )。 


加 LIST 1.2 


Ze python-dev 
sudo apt-get -y install python-dev 


Xr dE 


rox dt 


pip 是 管理 Python 第 三 方 库 的 工具 。 虽 然 它 


安装 pip 
wget https://bootstrap.pypa.io/get-pip.py 


sudo python get-pip.py 


安装 Python 相关 的 包 





也 能 通过 apt MEITE, BIRER IA 





较 低 ， 因 此 我 们 使 用 get -pip .py 来 安装 最 新 版 。 


至 此 Python 相关 的 包 已 经 


版 本 。 





E /= 
安装 完毕 。 





最 后 我 们 来 查看 一 下 Ubuntu WA Eg HJ Python 的 
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Ej LIST 1.3 查看 Python 的 版 本 


$ python =Y 
Pye noni 2.7.6 


输入 LIST 1.3 中 的 命令 ， 我 们 便 能 够 查看 到 当前 安装 的 Python JU, Ubuntu 默认 安装 的 是 
Python 2.7.0。 


ensurepip 

Python 3.4 具有 ensurepip 模块 ， 可 在 安装 Python 的 同时 捆绑 安装 pip。 这 个 模块 是 在 
Python 2.7.9 之 后 加 入 的 。 支 持 ensurepip 的 Python 可 以 直接 使 用 pip， 不 需要 执行 get-pip .py 
KHI. AIh, HT python -mensurepip -U 可 以 将 pip 更 新 到 当前 最 新 版 本 。 


ensurepip 
https://docs.python.org/2.7/library/ensurepip.html 


PEP 477: Backport ensurepip ( PEP 453 )to Python 2.7 
https://www.python.org/dev/peps/pep-0477 


1.1.2 E98 —758 
JH pip install 命令 可 以 安装 第 三 方 开发 的 包 。 
第 三 方 包 注册 在 PyPI 上 。 这 是 一 个 用 来 共享 Python 包 的 版 本 库 (Repository )， 任 何人 都 可 
以 将 Python 包 上 传 到 上 面 ， 同 时 也 可 以 从 上 面 自由 下 载 想 用 的 包 。 用 Python 开发 软件 时 ， 常 党 
要 从 PyPI 安装 所 需 的 包 。 














NOTE 
PyPI 的 读音 是 /par pi: ai/。 
PyPI 的 构造 类 似 Perl 中 的 CPAN”, Ruby 中 的 RubyGems”、PHP 中 的 PEAR ”等 。 





从 PyPI 安装 包 时 需要 用 到 pip 命令 。 


NOTE 
AX pip 的 详细 内 容 我 们 将 在 第 3 章 中 详细 了 解 。 


(D http://www.cpan.org/ 
2 nhttp://rubygems.org/ 
(2 nhttp://pear.php.net/ 
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这 里 简单 了 解 一 下 pip 的 使 用 方法 。 首 先 我 们 来 查看 当前 安装 的 pip 的 版 本 ( LIST 1.4 )。 


回 LIST 1.4 查看 pip 的 版 本 
$ pip --version 


pip 1.5.6 from /usr/local/lib/python2.7/dist-packages/ (python 2.7) 


可 以 看 到 当前 版 本 为 1.5.6 (20144 12 月 9 日 时 )。 


NOTE 


上 面 例子 中 的 pip 安装 在 dist- un 目录 下 ， 只 有 通过 debian M ubuntu & X 
Python 时 才 会 安装 到 这 个 特有 的 位 置 。 如 果 是 通过 Linux 发 行 版 、OS X、 源 码 安 装 ， 则 会 安装 
在 site-packages 目录 下 。 








通过 pip 安 法 第 三 方 包 的 方法 如 下 。 首 先 我 们 来 安装 常用 的 virtualenv 包 ( LIST 1.5 )。 


Ej LIST 1.5 通过 pip 安装 包 
$ gudo pip ingrtall virtualenwy 
- (中 间 省 略 ) - 
Successfully installed virtualenv 


Cleaning up... 


此 后 ， 包 的 安装 基本 都 要 用 pip 命令 来 完成 。 男 外 ， 上 面 例子 中 的 virtualenv 包 安 装 在 /usr/ 
local/lib/python2.7 目录 下 。 


NOTE 


pip 在 安装 一 些 需 要 构建 的 包 时 ， 会 用 gcc 等 编译 器 进行 构建 。 在 本 书 所 用 的 Ubuntu F, 
我 们 已 经 通过 build-essential 安装 了 gcc。Windows 下 需要 用 Microsoft Visual C++ Compiler 
for Python 2.7 或 者 MinGW 等 进行 安装 。 这 些 都 是 免费 的 。 


1.1.3 virtualenv 的 使 用 方法 


前 面 安 装 的 virtualenv 是 用 来 搭建 虚拟 Python 执行 环境 的 。 d 为 virtualenv 环境 
使 用 这 个 环境 时 ， 包 不 会 安装 到 /usrlocal/lib/bpython2.7 下 ， 而 是 安装 到 虚拟 virtualenv 环境 中 。 
由 于 我 们 在 前 面 已 经 完成 了 安装 ， 所 以 这 RE (LIST 1.6 )。 





"Fi, o 








Ə LIST 1.6 查看 virtualenv 的 版 本 


$ virtualenv --version 


isque 
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NOTE 
有 关 virtualenv 的 详细 内 容 我 们 将 在 第 3 章 中 详细 了 人 解 。 


我 们 在 未 使 用 virtualenv 的 状态 下 查看 当前 版 本 (LIST 1.7 )。 


© LIST 1.7 用 pip freeze 查看 当前 安装 版 本 


$ pip freeze 

BAM 04 2 

Tw SEEC= COFE=s13 .2.0 
apt-xapian-index--0.45 
argparse--1.2.1 


comtadgolbyec-q 7 





输入 pip freeze MS, RIERA SIT AERE /usr/local/lib/python2.7 目录 下 的 包 。 
接 下 来 新 建 virtualenv 环境 。 我 们 在 主 目录 (HOME 目录 ) 下 创建 工作 目录 ， 然 后 在 这 个 工 
作 目 录 下 搭建 virtualenv 环境 (LIST 1.8 )。 








© LIST 1.8 搭建 virtualenv 环境 


S mkdir ~/work 
$ cd -/work 


S virtualenv venv 


执行 LIST 1.8 中 的 命令 后 ，work 目录 下 会 目 动 生成 venv 目录 。 这 就 是 virtualenv 环境 的 
H 3K o 
接 下 来 我 们 启动 virtualenv 环境 。 


© LIST 1.9 ”启动 virtualenv 环境 


$ source venv/bin/activate 


(venv)S$ 


如 LIST 1.9 所 示 ， 通 过 source 命令 执行 activate， 启 动 virtualeny 环境 。 如 果 终 端的 
开头 显示 了 “(venv)”( 图 1.1), SEUEB virtualenv 环境 已 经 启动 。 








(venv)bpbookebpbook-ubuntu: -/work$ B 
1.1 activate 后 的 virtualenvy 的 状态 


我 们 在 启动 了 virtualenv 的 状态 下 再 次 执行 pip freeze， 查 看 当前 已 安装 的 包 ( LIST 1.10 )。 
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© LIST 1.10 在 虚拟 环境 下 查看 版 本 


(venv) $ pip freeze 
argparse--1.2.1 


wsdqgurer--0.1.2 
可 以 看 到 ， 在 virtualenv 环境 刚刚 搭建 完成 时 ， 这 个 Python 执行 环境 中 没有 添加 安装 任何 


包 C argparse, wsgiref 是 与 Python 本 体 捆绑 的 标准 库 )。 
想 关 闭 virtualenv 环境 时 ， 输 入 LIST 1.11 中 的 命令 即 可 。 


加 LIST 1.11 关闭 virtualenv 环境 


(venv) $ deactivate 


S 


如 果 我 们 不 再 需要 某 个 virtualenv 环境 (本 例 中 是 venv 目录 )， 则 可 以 直接 用 xm -R venv 
等 命令 将 其 连同 所 在 目录 一 起 删除。 








1.1.4 多 版 本 Python 的 使 用 


目前 ，Python 3.X 系列 和 2.X 系列 的 开发 是 并 行 的 ， 因 此 我 们 会 遇 到 不 同 项 目 使 用 不 同 版 
本 的 Python 的 情况 。 本 小 节 中 ， 我 们 将 学 习 如 何在 一 个 客 OS 环境 下 准备 多 个 版 本 的 Python, 
以 满足 不 同 应 用 的 需要 。 

Ubuntu 14.04 默认 安装 了 Python 2.7.6 和 Python 3.4.0。 








Ej LIST 1.12 查看 Python 的 版 本 


$ python3 -V 
Python 3.4.0 


9 python =V 
Python 2.7-6 


现在 我 们 将 Python 2.7 系列 的 最 新 版 本 Python 2.7.9" 22358 OS ( Ubuntu 14.04 ) 上 。 
Ubuntu 14.04 上 安装 Python 的 方法 有 下 列 几 种 。 


e 通过 Ubuntu 官方 deb 包 安 装 
e 通过 源 文件 构建 安装 
e 通过 PPA (Personal Package Archives, ^l AX FREE ) 以 deb 包 的 形式 安装 





通过 deb BWR FA in, (BEPERA 4E AESCPT Pythons RARA Python 


(D nttp://www.python.org/downloads/release/python-279/ 
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AAA 行 构 建 了 。 鉴 于 这 类 情况 ， 我 们 将 在 这 里 介绍 
过 源 文 件 构 建 ” 这 一 安装 方式 C LIST 1.13 )。 





加 LIST 1.13 ”通过 源 文件 构建 并 安装 

wget https://www.python.org/ftp/python/2.7.9/Python-2.7.9.tgz 

je: sa o T- 9 COZ 

GODS ons 79 

LDFLAGS-"-L/usr/lib/x86 64-linux-gnu" ./configure --prefix-/opt/python2.7.9 


make 


SOs OAs RUR OPs Op Uas 


sudo make install 


该 Python 将 被 安装 到 Se el 9/bin 下 ， 我 们 可 以 通过 文件 名 中 的 版 本 号 找到 它 。 现 
在 执行 Python 命令 查看 是 否 安装 成 功 ( LIST 1.14 )。 








加 LIST 1.14 查看 Python 2.7.9 


Sr ors Apoyo mane o Aum AA Ta e TS] 
Dye 2.7-9 


到 这 里 ，Python BJAZZ RELAY s BE POR Pert WERF EMH DS A385 He UIS BJ 
Python, 


NOTE 

f& Python 2.6 这 种 官方 apt 版 本 库 早 已 不 支持 的 旧版 本 ， 我 们 可 以 通过 PPA， 即 分 享 个 人 
软件 包 的 apt 版 本 库 进 行 安装 ( LIST 1.15 )。 但 要 注意 ，PPA 中 的 软件 包 全 都 是 个 人 上 传 的 ， 一 
切 使 用 后 果 要 由 自己 负责 。 


& LIST 1.15 通过 PPA 以 deb 包 的 形式 安装 


$ sudo add-apt-repository ppa:fkrull/deadsnakes 
$ sudo apt-get -y update 

$ sudo apt-get -y install python2.6 

$ python2.6 -V 

Python 2.6.9 


NOTE 

Python 的 部 分 模块 依赖 于 一 些 必 须 通过 apt 命令 进行 安装 的 包 。 对 于 这 类 Python 模块 ， 
如 果 不 事先 用 at 命令 安装 好 包 ， 则 会 发 生 ImportError。 

这 种 时 候 我 们 需要 先 用 apt 命令 安 狂 所 需 的 包 ， 然 后 再 通 Re 因此 如 果 各 
位 遇 到 Python 模块 无 法 使 用 的 情况 ， 可 以 考虑 重新 通过 源 文 件 构建 一 过 。 有 些 Python 的 标准 
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ESIAS SRL deb 包 才 能 使 用 ， 具 体内 容 如 下 所 示 。 


Python 模块 deb 包 
zlib zlib1g-dev 








sglite3 libsglite3-dev 





readline libreadline6-dev 
gdbm libgdbm-dev 
bz2 libbz2-dev 
Tkinter tk-dev 

















@ 借助 virtualenv 分 别 使 用 不 同 版 本 的 Python 

当 OS 中 安装 了 多 个 Python 时 ， 我 们 可 以 通过 完整 路 径 指 定 Python 命令 ， 或 者 使 用 市 版 本 
号 的 Python 命令 (如 python2.7 fI pychon3.4 ) 来 区 分 使 用 各 版 本 。 

不 过 ， 如 果 在 搭建 virtualenv 环境 时 指定 了 该 环境 下 的 默认 Python， 那 么 在 启动 该 环境 时 ， 
我 们 就 不 需要 顾虑 版 本 问题 了 。 








© LIST 1.16 指定 virtualenv 下 执行 的 Python 


$ virtualenv --python-/opt/python2.7.9/bin/python venv2 
$ source venv2/bin/activate 
(venv2)S 


Byrhom 247-9 


根据 LIST 1.16 进行 指定 之 后 ， 以 /opt/python2.7.9/bin/python 为 基础 的 virtualenv 环境 一 一 
venv2 就 搭建 完成 了 。 


1.2 ”安装 Mercurial 





版 本 控制 系统 在 如 今 的 开发 过 程 中 已 经 十 分 普及 ，Python 目 然 也 不 例外 。 人 们 使 用 版 本 控 
制 系统 通常 是 为 了 多 人 一 起 省 理 源码 ， 不 过 ， 将 它 引 入 到 个 人 开发 中 也 能 各 来 不 少 好 人 处。 比如 
在 开发 过 程 中 应 用 突然 不 工作 了 ， 我 们 就 可 以 将 其 回 济 成 能 正常 工作 的 版 本 。 为 外 ， 对 版 本 进 
行 管理 之 后 ,一旦 哪里 发 现 了 问题 ， 我 们 可 以 立刻 沿 时 间 线 查找 之 前 的 版 本 ,快速 找 出 问题 发 
生 的 时 间 点 。 

版 本 控制 系统 大 人 致 可 分 为 两 类 ， 一 类 是 CVS 和 Subversion 这 种 单一 版 本 库 的 版 本 控制 系 
统 ， 男 一 种 则 是 Mercurial 和 Git 这 种 分 布 式 版 本 控制 系统 ( Distributed Version Control System, 
DVCS )， 如 今 越 来 越 多 人 倾向 于 使 用 后 着 。Mercurial 这 种 分 布 式 版 本 控制 系统 最 大 的 优势 在 于 
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各 个 版 本 库 独 立 ， 因 此 在 创建 分 支 、 提 交 、 取 消 更 改 时 不 会 对 周围 人 造成 有 影响。 而 且 分 布 式 的 
版 本 库 可 以 各 目 看 作 是 彼此 的 备份 。 
接 下 来 我 们 来 了 解 一 下 Mercurial. 


1.2.1 Mercurial 概述 


Mercurial 是 Linux 内 核 的 开发 者 Matt Mackall F 2005 年 开始 开发 的 分 布 式 版 本 控制 系统 。 
Linux 内 核 之 父 Linus Torvalds 也 于 同期 开始 开发 Git。 如 今 这 二 者 已 经 成 为 分 布 式 版 本 控制 系统 
的 代表 ， 被 人 们 广泛 使 用 。 

由 于 Mercurial 本 号 就 是 由 Python 编写 而 成 的 ， 因 此 我 们 可 以 轻松 地 通过 pip 进行 安装 ， 也 
可 以 将 其 视 为 Python 程序 进行 自 定 义 设置 。 

对 熟悉 Python 的 用 户 而 言 易 于 上 手 ， 与 使 用 Python 进行 开发 的 团队 亲和力 高 ， 这 些 都 是 
Mercurial 的 优势 所 在 。 

此 外 ，Mercurial 的 魅力 还 在 于 内 置 了 基于 Web 的 管理 工具 ， 支 持 Bitbucket" 等 著名 源码 托 
管 服务 ，TortoiseHg” 等 GUI 客户 端 丰富 ， 等 等 。 

不 仅 如 此 ，Mercurial 的 命令 体系 与 广为人知 的 Subversion 很 类 似 ， 对 于 长 期 使 用 
Subversion 的 用 户 而 言 ， 要 比 Git 更 容易 上 手 。 














1.2.2 ”安装 Mercurial 





单 看 前 面 的 说 明 很 难 对 分 布 式 版 本 控制 系统 的 优势 有 一 个 明确 理解 ， 所 以 现在 我 们 通过 实 
际 的 安装 和 操作 来 体会 一 下 。 另 外 ， 高 级 的 Mercurial 运用 技巧 我 们 将 在 第 6 章 中 进行 学 习 ， 熟 
悉 Mercurial 的 读者 可 以 直接 跳 过 本 部 分 。 

Mercurial 与 其 他 程序 包 一 样 具 有 多 种 安装 方法 ， 用 户 可 以 通过 apt-get、pip、 源 文 
件 构 建 等 不 同 途径 进行 安装 。 这 里 我 们 为 保证 Mercurial 尽量 是 最 新 版 ， 决 定 选 用 pip 进行 安装 
CEIST LIT) 














© LIST 1.17 安装 Mercurial 


$ sudo pip install mercurial 


Mercurial 安装 完成 后 我 们 就 可 以 使 用 hg 命令 了 。 现 在 输入 hg --version 来 查看 版 本 
( LIST 1.18 )。 


(D http://bitbucket.org/ 
2 http://tortoisehg.bitbucket.org/ 
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E LIST 1.18 & & Mercurial 的 安装 情况 


$ hg --version 
Mercurial Distributed SCM (version 3.1.2) 


(see http://mercurial.selenic.com for more information) 


Copyright (C) 2005-2014 Matt Mackall and others 
This is free software; see the source for copying conditions. There is NO 


warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. 


1.2.3 创建 版 本 库 


在 创建 版 本 库 之 前 ， 我 们 先 准 备 好 Mercurial 的 环境 设置 文件 。 在 主 目录 下 创建 名 为 .hgrc 
的 文件 ， 然 后 进行 如 下 描述 。 其 中 括号 内 的 部 分 称 为 节 ( Section )， 比 如 [ui] 节 就 是 用 来 设置 
username 属性 的 。 

username 中 的 账户 信息 会 在 用 户 问 版 本 库 进行 提交 时 记录 在 日 志 中 。 各 位 请 将 日 己 的 账户 
名 和 邮箱 地 址 写 在 这 里 ( LIST 1.19 )。 











EJ LIST 1.19 设置 .hgrc 的 用 户 名 与 邮箱 地 址 
[ui] 


username=bpbook <bpbook@beproud.jp> 


[extensions] 
color= 


pager= 


[pager] 
pager-LESS-'FSRX' less 


[extensions] 节 用 来 激活 Mercurial 附属 的 扩展 工具 。 只 要 将 扩展 工具 名 写 入 [extensions] 17 
的 项 目 中 ， 我 们 就 可 以 使 用 该 工具 了 。 此 外 ， 某 些 扩展 工具 不 仅 要 在 [extensions] 中 设置 激活 ， 
还 需要 在 [pager] 广 中 设置 pager 属性 。 

完成 环境 设置 文件 之 后 就 该 创建 版 本 库 了 。 如 LIST 1.20 所 示 ， 我 们 为 版 本 库 创 建 一 个 目录 
并 移动 至 该 目录 下 ， 执 行 hg init 命令 创建 版 本 库 。 











Ə LIST 1.20 hg init ( 初始 化 版 本 库 ) 
$ mkdir -/hgtest 
$ cd -/hgtest 
$ hg init 
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1.2.4 文件 操作 


创建 好 版 本 库 之 后 让 我 们 给 它 实 际 添加 文件 。 现 在 创建 一 个 测试 用 的 文件 ， 查 看 当前 版 本 
库 的 状态 
查看 版 本 库 状态 用 hg status 命令 (LIST 1.21 )。 如 果 觉 得 每 次 输入 status KIRK, 
可 以 将 这 个 命令 缩写 为 ng st. hg 命令 为 用 户 准 备 了 部 分 缩写 形式 ， 感 兴趣 的 读者 可 以 参考 大 
助 或 其 他 资料 。 











Ej LIST 1.21 hg status ( 查看 状态 ) 


covutouch Lest-txt 


$ hg status 


2 test EXE 


文件 名 左 侧 显示 了 该 文件 在 版 本 库 内 的 状态 。 各 位 可 以 看 到 text.txt 文件 的 左 侧 显示 了 状态 
“?”， 这 代表 该 文件 现在 并 不 在 版 本 管理 的 范围 内 。 因 此 我 们 执行 ng aad 命令 将 其 添加 为 版 本 
管理 的 对 象 ， 如 LIST 1.22 所 示 。 





Ej LIST 1.22 hg add ( 添加 文件 ) 


one acel TEST. qst: 
$ hg status 


A test.txt 


执行 hg ada 之 后 我 们 再 进行 一 次 查看 ， 会 发 现 之 前 的 “?” 已 经 变 成 了 “A”。 这 代表 该 文 
件 是 新 添加 到 版 本 管理 里 的 。 

要 想 让 添加 文件 反映 到 版 本 库 ， 我 们 需要 进行 提交 。 提 交 时 请 按照 LIST 1.23 所 示 ， 输 入 
hg commit 命令 。 如 果 不 执行 ng commit ， 那 么 我 们 创建 的 文件 就 只 能 停留 在 当前 工作 的 机 需 
里 ， 不 会 反映 到 版 本 库 中 。 














© LIST 1.23 hg commit ( 提交 


$ hg eomm 
test commit 


HG: Enter commit message. Lines beginning with 'HG:' are removed. 
HG: Leave message empty to abort commit. 

IB d. == 

HG: user: bpbook «bpbookGebeproud.]jp- 
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HG: branch 'default' 
HG: added test.txt 


执行 hg commit 后 编辑 需 就 会 司 动 ， 用 来 记录 提交 时 的 相关 信息 与 注释 。 我 们 在 这 里 输入 
test commit, 

注释 输入 栏 下 方 显 示 着 branch 'default', iXX&m default 分 文 〈 版 本 库 创 建 时 就 存在 的 
分 文 ) 为 我 们 当前 进行 修正 /添加 操作 的 对 象 。 

















NOTE 
提交 时 打开 的 编辑 器 是 可 以 更 改 的 。 更 改 时 需要 如 下 例 所 示 ， 在 .hgrc 的 [ui] 节 里 添加 
editor 属性 。 


[ui] 


editor - vim 
这 表示 我 们 要 使 用 vim 编辑 器 。 默 认 局 动 的 编辑 器 取决 于 环境 变量 EDITOR， 环 境 变 量 可 
以 用 下 述 命令 查看 。 


$ echo SEDITOR 


vim 





提交 文件 之 后 用 hg status 查看 ， 结 果 应 该 如 LIST 1.24 所 示 ， 什 么 都 没有 。 


© LIST 1.24 提交 后 的 查看 


$ hg status 


接 下 来 我 们 看 看 如 何在 Mercurial 中 操作 编辑 过 的 文件 。 

先 用 编辑 硕 打 开 test.txt 进行 修改 ， 然 后 保存 文件 。 在 当前 状态 下 执行 hg status 后 ， 会 发 
现 该 文件 的 状态 变 成 了 M。 状 态 M 表示 该 文件 在 最 后 一 次 提交 之 后 又 进行 了 “变更 ”( Modify )。 
使 用 hg diff 命令 可 以 查看 变更 前 的 状态 (已 提交 的 文件 ) 与 当前 状态 的 差别 ( LIST 1.25 )。 














Ej LIST 1.25 hg diff ( 查看 差别 ) 


$ hg status 
M test.txt 


$ hg diff 
diff -r 74471564b074 test.txt 


--- a/test.txt Mon Oct 31 18*07:15 2074 0900 
tid ISV IEEE o CXE Monv occus es 
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Qo -0,0 +1,1 @@ 
+modify this file 





在 尚未 提交 的 状态 下 ， 我 们 可 以 使 用 hg revert 命令 撤销 编辑 ( LIST 1.26 ). 


Ej LIST 1.26 hg revert ( 撤销 编辑 ) 


$ hg revert test.txt 


NOTE 


hg revent 可 以 撤销 尚未 提交 的 内 容 ， 但 对 已 提交 的 内 容 无 效 。 这 种 情况 需要 使 用 hg 
commit --amend 命令 对 已 提交 的 变更 集 进 行 修 改 或 撤销 。 








Mercurial 的 基本 操作 方法 就 解说 到 这 里 ， 但 下 列 几 项 我 们 并 未 提 及 。 
e 分 文 的 操作 

e 远程 版 本 库 的 使 用 

e 以 团队 开发 为 前 提 的 Mercurial 的 使 用 方法 








上 述 几 点 我 们 将 在 第 4 章 和 第 6 草 中 详细 了 解 。 


1.3 ”编辑 器 与 辅助 开发 工具 


本 节 将 介绍 编写 Python 代码 时 可 用 的 编辑 各 ， 以 及 一 些 有 助 于 开发 的 小 贴 士 和 Python 
模块 。 





1.9.1 编辑 器 


编写 Python 代码 目 然 少不了 编辑 需 
辑 需 必须 具备 下 列 几 项 功能 。 








。 当 今 志 上 的 编辑 各 种 类 繁多 ,但 编写 Python 代码 的 编 


。 语 法 高 这 


将 语法 设置 高 完 是 














-项 十 分 重要 的 功能 。 用 特殊 字 色 或 字体 表示 关键 词 可 以 让 编程 人 员 
快速 发 现 拼 号 类 错误 。 这 样 一 来 ， 我 们 便 能 够 在 编写 代码 的 过 程 中 注意 并 修正 此 类 错误 。 
e 智能 缩 进 














自动 根据 语法 添加 缩 进 的 功能 。 特 别 是 对 于 Python 这 类 缩 进 具有 重要 意义 的 语言 ， 编 辑 


" 语法 高 亮 的 设置 


SIVE ax on 


$$ 1x Python AT] 








| 15 
dm I. E] 7] 48 ES EET mE CES EST PP) ERAI ed o 
e 执行 DEBUG 


在 编辑 器 上 执行 DEBUG 的 功能 。 比 如 在 编程 过 程 中 遇 到 某 些 问题 时 ， 如 果 能 直接 使 用 编 
辑 器 进行 DEBUG ， 那 么 将 和 





É 
e 可 以 使 用 议 态 解析 类 插件 





快 地 找 出 原因 ， 提 高 解决 问题 的 效率 。 
能 在 编辑 名 上 执行 静态 解析 类 捕 件 的 功能 。 如 于 


能 直接 在 编辑 船 内 执行 语法 高 完 无 法 查 
出 的 键入 错误 、 博 法 错误 、 编 码 格式 检查 等 ， 将 能 省 
减 修 改 时 消耗 的 时 间 。 








这 里 将 按照 上 述 4 点 ， 给 各 位 
功能 。 


介绍 


省 去 每 次 开关 编辑 瘟 的 抹 烦 ， 大 幅 前 





3 Fuss ( Vim、Emacs、PyCharm ) 的 使 用 方法 和 
各 位 可 以 以 此 为 参考 来 寻找 上 自己 用 看 顺手 的 编辑 规 
€ Vim 


Vim 是 一 球 功 能 强大 的 文本 编辑 从 





默认 搭载 在 许多 OS 上 ， 普 及 度 很 高 。 
Vim 可 以 通过 内 置 的 Vim script 脚本 语言 进行 功能 扩展 ， 因 此 存在 许多 捅 件 。 
语法 高 学 





默认 捆绑 Python 的 语法 高 亮 设置 文件 ( python.vim ) 。 
智能 缩 进 


有 目 动 缩 进 的 设置 选项 。 缩 进 时 插入 的 空格 效 也 可 以 调 世 。 
执行 DEBUG 





to/virtualenv/python -m pdb s 之 后 ， 编 人 
可 以 使 用 静态 解析 类 插件 


:!/path/ 
HAEA X) ZR P SAZ Jr RE TR. 
vim-flake8 插 件 可 以 检查 当前 打开 的 文件 并 发 出 问题 警告 。 
Vim 的 设置 在 主 日 录 “ .vimrc” 文 件 中 进行 


Vim 可 以 在 编辑 各 上 调 出 外 部 命令 ， 因 此 可 以 执行 pdb (后 述 )。 比 如 执行 


现在 我 们 来 设置 语法 高 亮 和 目 动 缩 进 ( LIST 1.27 )。 


我 们 写 在 该 文件 中 的 设置 将 反映 在 Vim 上 。 
© LIST 1.27 ”用 于 Python 的 设置 


" 自动 缩 进 的 设置 


filetype plugin indent on 





另外 ， 设 置 文件 本 号 也 可 以 根据 对 象 文件 类 下 


a: | Y PA 
EZE 


I 进行 分 割 。 下 面 ， 我 们 专门 为 Python 脚本 准 
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备 一 个 设置 文件 (LIST 1.28 )。 


Ə LIST 1.28 准备 Python 专用 的 设置 文件 
$ 前 EC /vn 
$ mkdir ~/.vim/ftplugin 
$ touch ~/.vim/ftplugin/python.vim 


我 们 在 这 个 python.vim 中 进行 针对 Python 的 设置 ， 以 方便 编写 Python 代码 。 


加 LIST 1.29 将 Tab 改 为 4 个 空格 
"将 “Tab” 和 替换 为 “空格 ” 
setl expandtab 
"X "Tab" 的 “ 缩 进 幅 度 ” 改 为 4 
setl tabstop-4 
" 自动 缩 进 时 的 “ 缩 进 幅 度 ” 改 为 4 
setl shiftwidth-4 
" 按 下 键盘 “Tab” 键 时 插入 的 空格 数 
" 这 里 设置 为 0 就 可 以 插入 “tabstop” 中 设置 的 空格 数 了 
setl softtabstop=0 
" 保存 时 删除 行 尾 的 空格 
autocmd BufWritePre * :%s/\s\+$//ge 
"80 个 字符 换行 
setlocal textwidth-80 


f& LIST 1.29 这 样 设置 是 为 了 迎合 Python 社区 推荐 的 PEP 8" 编码 格式 ( 后 述 )。 
vim-flake8 是 Vim 的 插件 , 需要 进行 安装 。neobundle.vim” 是 一 个 专门 用 来 管理 Vim 插件 的 


插件 ， 用 它 可 以 轻松 安装 其 他 Vim 插件 。 
安装 neobundle.vim 后 ， 我 们 在 “.vimre” 里 这 样 设置 vim-flake8. 





NeoBundle 'nvie/vim-flake8' 





现在 只 要 重启 Vim SEZJT AS CREE, ERAR, H Vim 打开 Python AL, fi P Ctrl + F7 
就 可 以 看 到 flake8 的 警告 BEI O 


NOTE 
python.org 官方 Wiki 上 也 记载 着 Vim 的 一 些 设置 资料 ， 各 位 不 妨 去 看 一 看 。 


- Vi Improved” 


(D https://www.python.org/dev/peps/pep-0008 
2 nhttps://github.com/Shougo/neobundle.vim 
© nhttps://wiki.python.org/moin/Vim 
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此 外 ， 在 Vim 官方 网 站 和 许多 民间 社区 中 都 能 找到 大 量 关 于 Vim 的 信息 。 
: Vim online” 


a’ 
“ vim-jp 


@ Emacs 

Emacs 是 Unix 系列 OS 长 期 汽 用 的 编辑 大。 该 编辑 融 可 以 用 Emacs Lisp 语言 进行 扩展 ， 
此 拥有 大 量 插件 。 如 今 的 Emacs 已 经 捆绑 了 python.el， 安 装 Emacs 之 后 可 以 直接 编写 Python 代 
码 ， 不 必 特 童 去 设置 。 

人 们 第 说 Emacs 是 一 个 环境 ， 不 过 我 们 在 这 里 主要 是 看 它 作 为 Python 编辑 从 的 特征 。 








。 语法 高 
内 置 python.el。 当 global-font-lock-mode 不 为 nil 时 ( 默认 ) 进行 语法 高 亮 。 
。 智能 缩 进 
python.el 会 按照 PEP 8 的 要 求 缩 进 到 指定 位 置 。 
e 执行 DEBUG 
Emacs 上 可 以 执行 papb。 
先 键 和 人 M-x pdb， 然 后 直接 在 minibuffer 里 运行 类 似 /path/to/virtualenv/ 
python -m pdb /path/ 人 to/app.py 的 pdb 命令 行 。 此 时 会 局 动 pdb 专用 的 缓冲 ， 我 们 
可 以 在 里 面 查看 源码 或 进行 调试 。 
e 可 以 使 用 静态 解析 类 插件 
flymake-python-pyflakes 可 以 在 编码 过 程 中 高 党 警告 。 








安装 完成 之 后 我 们 在 设置 文件 $SHOME/.emacs.d/init.el 中 设置 Tab 和 空格 的 执行 动作 。 田 
AF, Emacs 可 以 让 空格 和 Tab 文字 可 视 化 。 在 Python 中 ， 缩 进 是 语法 的 一 部 分 ， 所 以 建议 各 位 
先 将 这 些 设置 好 (LIST 1.30 )。 





加 LIST 1.30 空格 和 Tab 的 设置 


require 'whitespace) 


setq whitespace-style '(face tabs tab-mark spaces lines-tail empty)) 


( 

( 

(global-whitespace-mode 1) 

(setq-default tab-width 4 indent-tabs-mode nil) 
( 


setq indent-tabs-mode nil) 
flymake-python-pyflakes 等 插件 并 没有 捆绑 在 Emacs 中 ， 所 以 我 们 需要 通过 Emacs 的 版 本 


(D http://www.vim.org/ 
Q http://vim-jp.org/ 
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控制 系统 elpa 进行 安装 。 首 先 在 SHOME/.emacs.d/init.el 文件 中 进行 如 LIST 1.31 所 示 的 设置 。 


© LIST 1.31 elpa 的 程序 包 版 本 库 设 置 


(require 'package) 
(add-to-list 'package-archives 

'("melpa" . "http://melpa.milkbox.net/packages/")) 
(add-to-list 'package-archives 

'("marmalade" . "http://marmalade-repo.org/packages/")) 


(package-initialize) 


通过 elpa 安装 好 flymake 和 flymake-python-pyflakes 之 后 ， 我 们 再 进 
设置 。 


© LIST 1.32 flymake 的 设置 


require 'flymake) 


( 

(require 'flymake-python-pyflakes) 

(add-hook 'python-mode-hook 'flymake-python-pyflakes-load) 
( 


setq flymake-python-pyflakes-executable "flake8") 





设置 好 fymake， 我 们 编写 源码 时 就 能 在 Emacs 上 看 到 flakes 的 警告 了 。 


NOTE 
python.org 上 有 设置 Emacs 的 相关 资料 。 


* Emacs Editor” 


另外 ， 我 们 在 其 官方 网 站 和 许多 Wiki 上 也 能 找到 大 量 Emacs 的 信息 。 


: GNU Emacs" : EmacsWiki / * Python Programming In Emacs" 


€ PyCharm 


对 长 期 以 来 使 用 Eclipse 等 IDE ( Integrated Development Environment， 集 成 开发 环境 


LIST 1.32 所 示 的 


) 进行 


开发 的 人 来 说 ，IDE 用 起 来 要 比 编辑 锅 顺 手 得 多 。 在 当今 众多 的 IDE 中 ， 普 及 率 较 高 的 当 属 


PyCharm qe 


PyCharm 是 一 款 2010 年 左右 问世 的 IDE， 为 Windows, OS X, Linux 等 OS 提供 了 相应 的 
装 程 序 ， 同 时 还 支持 Python 的 Web 框架 Django。PyCharm 有 多 种 许可 证 形态 ， 比 如 付费 的 


https://wiki.python.org/moin/EmacsEditor 


http://www.emacswiki.org/ 


AUR 

(D 

Q http://www.gnu.org/software/emacs/emacs.html 

© 

(4 http://www.emacswiki.org/emacs/PythonProgrammingInEmacs 
© 


http://www.jetbrains.com/pycharm/ 
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Pro 版 和 免费 的 Community 版 等 。 其 中 付费 的 Pro 版 还 提供 30 天 的 免费 使 用 期 。 

Ej Vim 和 Emacs 相 比 ，PyCharm E? T TF Z Python 开发 的 辅助 功能 ， 在 安装 完 之 后 可 以 
立刻 使 用 。 相 对 地 ， 目 行 开 发 插件 则 需要 应 用 Java 的 知识 ， 所 以 并 不 算 容 易 。 从 这 种 角度 来 
讲 ， 这 款 工具 可 能 并 不 适合 极 客 们 使 用 。 

如 果 各 位 实在 无 法 适应 Vim 或 Emacs， 那么 建议 先 尝 试 PyCharm 的 Community 版 。 它 作 
为 编写 Python 时 使 用 的 IDE， 具 有 以 下 特征 。 








e 语法 高 完 

标准 功能 。PyCharm 会 根据 当前 项 目 使 用 的 Python 版 本 切换 语法 及 内 置 吨 数 等 文字 的 高 
党 效果 。 

PyCharm 标 准 支 持 Python、HTML、CSS、JavaScript、XML、SQL 以 及 CoffeeScript、 
Angular JS、LESS、SASS、SCSS 等 格式 的 高 完 显 示 。Pro 版 还 文 持 Django、Mako、 
Jinja2、Web2py、Chameleon 模 板 的 记 法 。 

智能 缩 进 

标准 功能 。PyCharm 会 按照 PEP 8 的 要 求 缩 进 到 指定 位 置 。 

与 语法 高 亮相 同 ，PyCharm 也 文 持 Python 以 外 的 其 他 格式 。 另 外 ， 用 户 还 可 以 对 各 个 项 
目的 各 个 声言 进行 详细 设置 ， 比 如 规定 插入 Hard Tab 还 是 空格 等 。 

执行 DEBUG 

标准 功能 。IDE 中 可 以 设置 新 点 、 逐 名 执行、 显示 执行 中 的 变量 仁 。Pro 厂 可 以 用 手边 终 
端的 IDE 调 试 远程 服务 右上 的 进程 。 























e 前 仿 解 术 类 功能 
标准 功能 。 在 编写 代码 的 过 程 中 ，PyCharm 会 高 党 显示 对 未 使 用 的 变量 、 未 定义 的 名 
称 、 已 过 期 函数 的 警告 等 。 另 外 ，PyCharm 在 执行 解析 功能 时 会 从 多 角度 分 析 Python 代 
码 是 否 存 在 风险 。 








导入 PyCharm 之 后 ， 我 们 就 可 以 不 再 为 搭建 环境 劳 神 费心 了 。 它 为 用 户 标 配 了 大 量 功能 ， 
大 部 分 人 都 可 以 在 默认 设置 的 状态 下 轻松 使 用 。 不 过 相对 地 ， 一旦 习惯 了 这 些 懒 办 法 ， 当 极 客 
的 乐趣 目 然 也 会 大 打折 扣 。 

PyCharm 也 并 不 适用 于 所 有 情况 ， 比 如 编辑 单个 文件 就 很 肪 烦 。 这 种 情况 需要 先 创建 一 个 
空 项 目 ， 把 竺 编辑 的 文件 加 入 项 目 之 后 才能 打开 编辑 。 另 外 ，PyCharm 的 使 用 环境 建议 内 存 为 
2 GB 以 上 ， 显 示 带 为 SXGA 以 上 。 
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PyCharm 适合 用 来 干什么 

PyCharm3 及 之 前 的 版 本 以 提供 面向 Web 开发 者 的 辅助 功能 为 主 。 从 2014 年 11 月 发 布 的 
PyCharm4 开始 ， 该 系列 IDE 开始 内 置 Python notebook 等 功能 ， 预 计 今 后 会 逐步 增添 科学 计 
算 相 关 的 辅助 功能 。 


13.2 ”开发 辅助 工具 
本 部 分 将 向 各 位 介绍 一 些 Python 开发 过 程 中 应 当 了 解 的 模式 及 Python 包 。 


e 交互 模式 
单独 执行 python 命令 时 ， 该 命令 会 以 交互 模式 执行 。 交 互 模式 指 通 过 对 话 方 式 输入 并 执 
fT Python 代码 的 模式 。 现 在 请 直接 输入 python 命令 (LIST 1.33 )。 


B LIST 1.33 启动 交互 模式 


$ cpython 

Pyutuonecse quce demand Ma 22 0200 EDO) 

[Gocoa2 8-21 nn 

Type "help", "copyright", "credits" or "license" for more information. 


222 


随后 系统 会 进入 等 待 输入 的 状态 。 我 们 可 以 在 这 个 状态 下 直接 编写 Python 代码 。 代 码 执行 
后 的 内 容 会 直接 显示 在 屏幕 上 (LIST 1.34 )。 














Ej LIST 1.34 Python 代码 执行 示例 


>>> import sys 

>>> yS- PALM 

M usr/lib /python2. 7 "/usr/lib/python2.//plat-x86 64 LINnuUx on. 

ı /usr/Lib/pychon2 .7/Lilb=-tk', 1 /usr/1lib/python2 .7/16 ， 
'/usr/lib/python2.7/lib-dynload', '/usr/local/lib/python2.7/dist-packages', 
'/usr/lib/python2.7/dist-packages'] 


222 


我 们 导入 了 标准 模块 sys 并 显示 了 Python 包 的 搜索 路 径 列 表 。 
最 后 一 次 执行 的 结果 存储 在 变量 ”” 中 ， 执 行 它 就 可 以 返回 相同 结果 。 交 互 模式 让 我 们 能 
随手 轻松 地 查看 代码 ， 方 便 进行 DEBUG 等 操作 。 如 采 想 结束 交互 模式 ， 可 以 按 Ctrl + d 或 输入 


exit().; 
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NOTE 

交互 模式 在 启动 时 会 读 取 环 境 变 量 PYTHONSTARTUP 中 设置 的 文件 。 如 果 各 位 在 启动 交 
互 模式 时 想 顺 便 导 入 些 什么 ， 可 以 在 这 里 进行 设置 。 

另外 ，IPython 模块 可 以 将 Python 的 交互 模式 用 作 调 试 器 。 该 模块 可 通过 pip 安装 。 


$ sudo pip install ipython 


导入 IPython 后 ， 交 互 模式 会 实现 下 述 功能 
: TAB 键 补 全 代码 

: 使 用 通常 的 Shell 命令 

: 与 pdb ( 调试 器 ) 联动 


@flake8 ( 编码 格式 /语法 检测 ) 

为 更 好 地 规范 和 优化 Python， 人 们 以 社区 为 中 心 给 Python 制定 了 PEP ( Python Enhancement 
Proposals, Python 增强 建议 书 ) ”指导 规范 。 

其 中 PEP 8 主要 规范 Python 的 编码 格式 。 这 里 即将 介绍 的 flakes 模块 就 可 以 检查 我 们 的 代 
码 是 否 符合 该 编码 格式 。 如 LIST 1.35 所 示 ，flake8 可 通过 pip 安装 。 





© LIST 1.35 ”安装 flake8 


$ sudo pip install flake8 


flake8 不 但 能 检查 编码 格式 ， 还 可 以 帮助 我 们 找 出 语法 错误 以 及 一 些 已 导入 但 未 被 使 用 的 
模块 并 发 出 警告 。 
使 用 方法 很 简单 ， 只 要 像 LIST 1.36 一 样 指 定 文件 并 执行 flake8 命令 即 可 。 


加 LIST 1.36 flake8 执行 示例 


$ flake8 sample.py 

sample.py:1:12: E401 multiple imports on one line 
sample.py:1:17: E703 statement ends with a semicolon 
sample.py:3:1: E302 expected 2 blank lines, found 1 


280: E501 Line too long (93 > 79 mace en e) 


l 
3 
sample.py:4:5: E265 block comment should start with '$4 ' 
sample.py:4 
5 


sample.py:5:15: E225 missing whitespace around operator 


(D https://www.python.org/dev/peps 
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NOTE 
由 于 我 们 平时 使 用 的 是 flake8， 所 以 这 里 只 对 它 进 4 
PyLint 等 ， 各 位 可 以 根据 自己 的 开发 风格 选用 合适 的 模块 。 


| 
一 | 
xd 
Bs 
NS 
PE 
Hk 
3l 
E 
m) 
(3T 
EX 
di 


€ pdb ( 调试 器 ) 

最 后 我 们 来 了 解 一 下 Python 的 调试 硕 。 如 果 各 位 曾经 用 过 C 语言 的 gdb 等 调试 机， 或 者 对 
IDE 等 上 面 附属 的 调试 硕 有 所 接触 ， 那 么 一 定 不 会 对 插入 断 点 、 逐 句 执行 等 功能 感到 卫生 。 
Python 的 调试 器 也 具备 这 些 功能 。 

pdb 是 Python 的 标准 模块 ， 不 必 另 外 安 狗 。 其 最 简单 的 用 法 束 是 在 我 们 硕 望 程序 俘 止 的 位 
置 插入 如 LIST 1.37 所 示 的 代码 。 





Ej LIST 1.37 pdb 的 插入 代码 


def add(x, y): 


TACUT x pO: 


xs 0 
importe Pelo; pelo. set crace() 
x = ade (1, 2) 


执行 这 个 插入 了 LIST 1.37 中 的 代码 的 Python 脚本 时 ， 脚 本 会 停 在 上 述 搬入 代码 的 位 置 ， 
然后 启动 对 话 型 界面 。 


© LIST 1.38 pdb 执行 示例 


$ python pdbtest.py 

> pdbtest.py (7) «modules»() 
=>> x = addi (i, 2) 

(Pdb) 


本 下 我 们 对 一 些 辅助 开发 的 工具 、Python 程序 包 等 作 了 了 解 。 由 于 涉及 范围 较 广 ， 我 们 只 
简单 学 习 了 部 分 使 用 方法 。 有 关 这 些 工 具 、 程 序 库 的 详细 信息 请 各 位 日 行 得 阅 相 天文 档 。 


1.4 小结 








本 章 对 下 列 话题 进行 了 介绍 ， 意 在 指导 各 位 完成 Python 语言 独立 开发 的 事前 准备 。 








e 7X Python 
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e 安装 Mercurial 


e 编辑 器 和 DEBUG 工具 





为 保证 开发 前 的 准备 工作 ， 本 章 介 绍 了 许多 工具 的 安装 方法 。 这 里 介绍 的 很 多 内 容 在 
Ubuntu 以 外 的 OS 上 同样 适用 。 此 外 ， 各 位 还 可 以 编写 目 动 完 成 安装 的 Shell 脚本 ， 或 者 省 略 
并 简化 本 书 介绍 的 步骤 等 ， 总 之 能 做 的 事情 还 有 很 多 。 各 位 请 根据 自己 的 需要 搭建 适合 目 己 的 
环境 。 




















NOTE 


进入 第 2 章 之 前 ， 我 们 先 来 看 一 下 The Zen of Python。The Zen of Python 是 Python 开发 
者 之 一 Tim Peters 撰写 的 文章， 通过 19 个 分 项 简明 扼要 地 表达 了 Python 的 特点 。The Zen of 
Python ZI E (E73 RER 20 ”公开 发 表 ， 在 交互 模式 下 输入 import this 命令 也 可 以 看 到 这 篇 文章 。 
我 们 强烈 建议 各 位 去 读 一 读 。 


>>> import this 


另外 ，@atsuoishimoto 在 博客 上 对 The Zen of Python 进行 了 详细 讲解 ， 各 位 不 妨 参考 
Ee 
: The Zen of Python f Et - 前 篇 "(Bi ) 


: The Zen of Python f zi - IE BIE) 


(D https://www.python.org/dev/peps/pep-0020 
© http://www.gembook.org/2010-09-20.html 
© http://www.gembook.org/2010-09-26.html 


A2% FA Web 应 用 


本 章 中 ， 我 们 先 来 了 解 Web B 的 概念 ， 然 后 一 Nd PURA 留言 板 应 用 ， 信 此 
来 了 解 Web 应 用 开发 的 基本 流程 。 至 于 留言 板 应 用 ， 它 类 似 于 观光 景点 的 留 E n 
网 站 的 人 在 上 面 添加 留言 ， 说 日 了 eal leo 言 板 。 正 文中 会 涉及 HTML/CSS 和 
Python 代码 ， 但 本 书 将 省 去 对 这 些 语法 的 说 明 。 男 外 ， 本 草 的 开发 环境 为 VirtualBox 虚拟 机 上 
的 Ubuntu 和 Python 2.7， 同 时 还 会 用 到 virtualenv。 








2.1 了 解 Web 应 用 








要 想 开 发 Web 应 用 ， 首 先 要 知道 Web 应 用 是 什么 ， 它 是 怎样 工作 的 。 所 以 我 们 先 来 了 解 一 
下 什么 是 Web 应 用 。 





2.1.1 Web 应 用 是 什么 


顾名思义 ，Web 应 用 就 是 可 以 通过 网 络 使 用 的 应 用 程序 。 比 如 Google 的 搜索 服务 、Gmail、 
Wikipedia、 各 种 博客 服务 Twitter 等 迷你 博客 、GREE 和 手机 游戏 、Facebook 等 社交 网 站 以 及 
上 面 的 社交 洲 戏 等 ， 这 些 都 是 Web 应 用 。 人 们 使 用 Web 应 用 时 需要 通过 Web 训 览 骨 访 问 〈 连 
接 ) 相应 服务 。 

那么 ， 同 样 需要 通过 Web 浏览 如 阅览 的 Web 站 点 又 如 何 呢 ? Web 站 点 只 是 单纯 地 显示 页 
面 ， 它 们 能 称 作 Web 应 用 吗 ? 

答 肥 是 不 一 定 。 某 些 Web 站 点 或 许可 以 称 为 Web 应 用 。 因 为 虽然 有 些 东 西 在 阅览 者 眼中 像 
Web 站 点 ， 但 它 实 际 上 却 是 由 CMS (Content Management System ， 内 容 管理 系统 ) 等 Web 应 用 
构成 的 。Web 浏览 硕 会 从 访问 对 象 的 计算 机 (服务 器 ) 中 下 载 HTML, 、CSS、 图 片 等 各 种 内 容 ， 
然后 再 把 这 些 内 容 显示 在 我 们 的 屏幕 上 。 如 采 负 责 发 送 内 容 的 服务 融 只 是 返回 一 些 早已 准备 好 
的 静态 内 容 ， 那 么 这 个 Web 站 点 就 不 能 称 作 Web 应 用 。 只 有 人 能够 动态 生成 并 返回 内 容 的 系统 
( 比如 通过 Web 浏览 硕 接 收 用 户 输入 的 数据 ， 再 根据 这 些 数 据 生成 内 容 ) 才能 称 作 Web 应 用 。 




















NOTE 
CMS 是 负责 管理 和 发 送 文章 、 图 片 等 内 容 的 系统 。Wiki 和 博客 系统 也 都 属于 CMS。 
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2.1.2 Web 应 用 与 果 面 应 用 的 区 别 


要 通过 Web 浏览 器 连接 服务 需 使 用 的 应 用 叫 Web 应 用 ; 相对 地 ， 要 将 软件 安装 在 计算 机 上 
才能 使 用 的 应 用 叫 捍 面 应 用 。 二 者 的 区 别 如 下 。 














比较 项 目 Web 应 用 桌面 应 用 
服务 器 " 可 有 可 无 

网 络 连 接 E 部 分 应 用 需要 
使 用 OS 具备 的 功能 不 可 能 
不 需要 
升级 不 需要 使 用 者 专门 注意 需要 使 用 者 亲自 动手 
跨 平 台 使 用 有 Web 浏览 器 就 能 需要 各 平台 分 别 作 处 理 
与 PC 端 基本 相同 需要 各 平台 分 别 作 处 理 
慢 快 



































从 这 张 表 上 看 ， 二 者 各 有 所 长 。 但 如 有 果 要 开发 一 个 让 使 用 者 通过 网 络 互 相交 流 信 息 的 应 用 ， 
那么 由 于 喝 面 应 用 也 同样 需要 用 到 服务 闫 ， 所 以 使 用 Web 应 用 开发 起 来 会 简单 很 多 。 不 过 ， 这 
个 表 中 的 内 容 也 不 是 一 成 不 变 的 。 

比如 Web 应 用 本 来 离 不 开 网 络 ， 但 如 今 已 有 一 部 分 应 用 可 以 离线 运行 。 男 外 ， 某 些 虹 面 应 
用 也 开始 具备 目 动 升级 新 版 本 的 功能 ( 比如 Google Chrome )， 这 让 使 用 者 不 必 再 费心 手动 升级 。 
可 以 说 ，Web 应 用 和 吕 面 应 用 之 间 的 距离 正在 逐渐 缩小 。 




















2.1.3 Web 应 用 的 机 制 
接 下 来 我 们 来 了 解 一 下 Web 应 用 的 机 制 。 





从 我 们 在 Web 浏览 需 中 输入 URL 到 显示 出 页 面 ， 其 间 要 进行 下 述 处 理 。 

(D 用户 在 Web 浏览 需 中 输入 URL 

(2) 向 DNS 服务 器 询问 该 URL 中 的 域名 ， 获 取 IP 地 址 

(3) Web 浏览 器 连接 该 IP 地址 的 Web 服务 器 ， 开 始 HTTP 通信 

(4) Web 服务 需 根 据 HTTP 发 送 来 的 信息 运行 Web 应用， 获取 相应 内 容 

© Web 服务 器 响应 ， 返 回执 行 应 用 后 得 到 的 HTML、CSS、JavaScript、 图 片 文件 等 内 容 
(6) Web 浏览 器 将 收 到 的 内 容 显 示 在 页 面 中 














下 表 是 对 上 述 处 理 流程 中 的 术 堵 进行 的 说 明 。 
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通过 HTTP 等 协议 与 URL 所 示 的 计算 机 通信 ， 将 HTML、CSS、 图 片 等 内 容 显示 在 页 面 中 的 软件 


Uniform Resource Locator ( 统一 资源 定位 符 ) 的 简称 ， 其 中 包含 域名 。 这 个 字符 串 用 来 表示 计算 机 
需要 访问 网 络 上 的 哪些 内 容 





与 IP 地 址 挂钩 的 字符 串 ( 比如 URL 中 包含 的 www.beproud.jp 等 字符 串 ) 
DNS 服务 嚣 。 | 可 以 通过 域名 查询 IP 地 址 的 服务 器 





IP 地 址 


个 数值 用 来 在 了 网络 上 识别 我 们 想 访 问 的 计算 机 ( 以 1Pv4 地 址 为 例 ，IP 地 址 由 0 ~ 255 的 数字 和 
id 比如 192.168.0.1 ) 


Hypertext Transfer Protocol ( 超 文 本 传输 协议 ) 的 简称 ， 是 与 被 访问 计算 机 之 间 的 通信 协议 





用 来 描述 文档 ( 包括 文字 和 图 片 等 ) 结构 的 语言 
CSS 描述 HTML 等 语言 描述 的 文档 该 如 何 显示 的 语言 、 机 制 





JavaScript 在 Web 浏览 器 上 运行 的 程序 





Web 服务 器 通过 HTTP 进行 通信 的 服务 器 程序 / 计算 机 





Web 应 用 在 Web 服务 器 上 运行 的 程序 











CGI Common Gateway Interface ( 通用 网 关 接 口 ) 的 简称 ，Web 应 用 的 机 制 之 一 





上 述 流程 可 以 用 图 2.1 表示 。 










GD 输入 URL ES @ [8] | PHE HE 
— —— = 
4 ————— |. 
HP ” @ 显 示 页 面 IP 地 址 X 
Web 浏览 器 DNS 服务 器 
(OHTTP3& fS 
(4 执行 Web 应 用 
. | = 
JP: 
CSS (C— 
- 内 容 
html W b N 
Web 服务 器 ob RH 
(9 过 响应 返回 内 容 


图 2.1 Web 应 用 的 处 理 流程 


€ Web 应 用 与 CGI 


CGI 是 Web 服务 需 运 行 Web 应 用 的 一 种 机 制 。Web 服务 需 执 行 CGI 程序 ( CGI 脚本 )， 然 
后 将 该 程序 的 标准 输出 结果 作为 HTTP 通信 的 啊 应 返回 给 对 方 。 最 人 简单 的 CGI 程序 就 是 在 控制 











台 界 面 上 显示 字符 串 。 


CGIHTTPServer 是 Python 标准 模块 中 的 web 服务 器 ， 它 可 以 运行 CGI 程序 。 现 在 我 们 试 


着 运行 下 面 这 个 CGI 程序 ( LIST 2.1 )。 
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加 LIST 2.1 hello.py 


=I /usr/bin/eny python 

print 200 OKU 

print "Content-Type: text/plain" 
prane o 


prime "Hello CGI 14 
用 python 命令 运行 这 个 脚本 ， 人 然后 控制 全 界面 中 将 显示 如 LIST 2.2 所 示 的 4 行 字 符 串 。 


© LIST 2.2 ”用 python 命令 运行 hello.py 的 结果 


$ python hello.py 
290 D 
Content-Type: text/plain 


Hello CGI! 


用 CGIHTTPServer 运行 CGI 程序 时 ， 待 运行 文件 必须 位 于 cgi-bin 目录 下 ， 所 以 我 们 要 创 

这 个 目录 并 将 hello .py 放 进 去 。 男 外 ， 必 须 具 有 运行 权限 才 可 以 运行 这 些 文件 ， 因 此 还 要 
a chmod 命令 赋 子 运行 权限 。 配 置 好 CGI 程序 之 后 ， 我 们 就 可 以 按照 下 面 的 例子 ， 用 python 
命令 的 -m 选项 运行 CGIHTTPServer 了 。 





Ej LIST 2.3 CGI 程序 的 配置 与 CGIHTTPServer 的 运行 
$ mkalir oa 
$ mv hello.py cgi-bin/ 
$ chmod u+x cgi-bin/hello.py 
$ python -m CGIHTTPServer 
Serving HITE oa 0.0.0.0 port 8/000 -oo 





执行 LIST 2.3 中 的 命令 后 ， 在 该 环境 (这 里 是 VirtualBox 上 的 Ubuntu ) 的 8000 端口 等 待 请 
求 的 Web 服务 硕 将 会 局 动 。 (MET Ctrl + C 键 可 以 关闭 服务 硕 。 
要 想 通过 本 地 环境 ( 主 OS ) 的 Web 浏览 可 查看 效 末 ， 我 们 需要 先 设 置 冰 口 转发 。 设 置 方法 
与 附录 B 中 介绍 的 SSH 端口 的 设置 方法 一 样 ， 这 里 我 们 给 VirtualBox 的 端口 转发 添加 如 下 设 
、 客 端口 均 为 8000， 协 议 为 TCP。 
se ais 我 们 只 过 Web 浏览 器 访问 http://127.0.0.1:8000/ 
cgi-bin/hello.py， 即 可 看 到 Hello CGI! 字样 。 














NOTE 


127.0.0.1 代表 的 是 自己 的 计算 机 的 IP 地址。 设置 过 VirtualBox 的 端口 转发 之 后 ， 我 们 对 自 
己 的 计算 机 ( È OS ) 的 8000 端口 的 访问 会 被 转发 到 客 OS 的 8000 端口 。 


28 | 第 1 部 分 Python 开发 入 门 


本 例 中 的 CGI 程序 由 Python 代码 编写 而 成 。 实 际 上 ， 只 要 CGI 程序 能 够 进行 标准 输出 ， 
用 任何 语言 都 没有 问题 。 


€ Web 应 用 与 应 用 服务 器 

应 用 服务 需 指 能 运行 Web 应 用 的 功能 旦 能 与 Web 服务 器 通信 的 服务 器 。 人 处 于 启动 状态 的 应 
用 服务 帮会 一 直 等 待 Web 服务 右 发 来 请 求 ， 一 旦 接 到 请 求 便 会 运行 Web 应 用 并 返回 结果 。 由 于 
得 运行 的 程序 一 下放 在 内 存 里 ， 所 以 它 的 速度 通常 要 比 CGI 程序 的 速度 更 快 。Web los sw 
用 服务 絮 之 间 的 通信 协议 通常 为 HTTP 或 FCGI 等 。 如 果 一 个 应 用 服务 器 可 以 通过 HTTP 通信 ， 
那么 我 们 就 可 以 用 Web Tl Và as VIII o 

本 音 使 用 的 Flask 内 置 了 用 于 开发 的 应 用 服务 各 ( Web 服务 硕 )， 因 此 不 需要 再 另外 准备 
Web IRA AF o 














2.2 MEEA 


接 下 来 我 们 需要 为 开发 Web 应 用 做 一 些 前 置 准 备 。 这 里 需要 使 用 Python fI virtualenv, — 
T B ACRIBAS Is. 





2.2.1 关于 Flask 














开发 留言 板 应 用 时 ， 我 们 会 用 到 Flask"， 因 此 需要 事先 安装 。Flask 是 一 个 用 Python 编写 的 
Web MHIE, ERS T Werkzeug ( WSGI 实用 工具 ) 和 Jinja? (ERSE ) 两 个 库 。 用 它 可 以 
轻松 完成 小 规模 的 应 用 程序 开发 。 





2.2.2 Z% Flask 
安装 Flask 之 前 ， 我 们 先 用 virtualenv 命令 搭建 开发 应 用 所 需 的 虚拟 环境 。 用 LIST 2.4 中 的 
命令 可 以 搭建 出 名 为 venv 的 虚拟 环境 。 


B LIST2.4 搭建 名 为 venv 的 虚拟 环境 
S virtualenv venv 
通过 source 命令 执行 venv/bin 目录 下 的 activate 脚本 ， 启 动 我 们 刚刚 搭建 好 的 虚拟 环境 
(LIST 2.5 )。 执 行 完 成 后 ， 命 令 提 示 符 上 会 显示 虚拟 环境 名 (venv) 。 





(D http: //flask.pocoo.org/ 
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© LIST 2.5 启动 虚拟 环境 venv 


$ source venv/bin/activate 


NOTE 
Windows 需要 使 用 venw\Scripts\activate 命令 启动 虚拟 环境 。 





接 下 来 使 用 pip 命令 在 虚拟 环境 上 安装 最 新 版 本 的 Flask。 我 们 需要 在 venv 虚拟 环境 处 于 激 
活 状 态 时 执行 LIST 2.6 中 的 命令 。 


加 LIST 2.6 用 pip 命令 安装 Flask 


$ pip install -U Flask 


指定 -U 选项 之 后 ， 可 以 用 新 版 本 替换 已 经 安装 的 旧版 本 。2014 年 12 月 时 ， 最 新 的 Flask 
版 本 为 0.10.1。 至 此 Flask 安装 完毕 ， 前 置 准 备 结 


2.3 Web 应 用 的 开发 流程 


那么 ， 接 下 来 我 们 应 该 按 什 么 顺序 开发 Web 应 用 呢 ? 

现在 唯一 硝 定 下 来 的 事情 就 是 要 开发 一 个 留言 板 应 用 ， 除 此 之 外 毫 无 计划 。 于 和 抑 我 们 有 要 确 
定 这 个 应 用 的 需求 ， 再 以 需求 为 出 发 点 考 夸 如 何 实现 页 面 和 功能 ， 然 后 开始 禹 代码 。 等 编码 完 
成 后 ， 还 要 测试 该 应 用 是 否 能 够 正常 运行 。 

整个 流程 总 结 起 来 是 下 面 这 样 的 。 








CD 确认 需求 (确认 要 开发 什么 应 用 ) 
D 根据 需求 明确 成 品 必 备 的 功能 
C) 根据 功能 明确 成 品 必 备 的 页 面 
D 页 面 设计 

(5) 实现 功能 

(6) 将 功能 植 人 到 页 面 中 

CD 确认 是 否 能 正 稼 运行 

®© 完成 








天 于 上 述 各 流程 ， 我 们 将 在 实际 开发 过 程 中 详细 了 解 。 
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2.4 明确 要 开发 什么 应 用 
这 里 ， 我 们 来 了 解 一 下 这 个 应 用 的 需求 以 及 必 备 功能 和 页 面 。 


2.4.1 留言 板 应 用 的 需求 


首先， 我 们 来 确定 留言 板 应 用 是 个 什么 样 的 应 用 ， 需 要 实现 些 什么 4 即 需求 )。 

如 有 果 不 事先 明确 知 求 或 规格 ,很 容易 在 编码 过 程 中 遇 到 “原本 想 做 什么 来 着 ”“ 这 个 功能 有 
必要 做 吗 ”之 类 的 问题 ， 导 致 项 目 一 团 乱 。 

因此 我 们 需要 先 确定 这 个 留言 板 应 用 的 需求 ， 其 具体 内 容 如 下 。 

















CD E Web 浏览 各 上 显示 一 个 包含 “提交 留言 ”表单 的 页 面 

D 可 以 在 提交 留言 表单 中 输入 名 字 和 留言 正文 

O 通过 提交 留言 表单 发 送 的 名 字 和 留言 内 容 会 被 保存 

由 已 保存 的 名 字 、 留 言 、 提 交 日 期 会 显示 在 页 面 中 

C) 整个 应 用 由 一 个 页 面 构成 ， 页 面 上 部 为 提交 留言 表单 ， 下 部 显示 已 提交 的 内 容 
© 提交 的 内 容 按 新 旧 顺 序 由 上 到 下 排列 

CD 可 经 由 网 络 (互联 网 ) 使 用 本 系统 

(& 可 同时 在 多 台 计 算 机 上 显示 已 提交 的 内 容 









































2.4.0 ”明确 必 备 的 功能 


确定 好 该 应 用 的 需求 后 ， 我 们 来 思考 一 下 该 用 哪些 功能 来 满足 这 些 震 求 。 

这 次 我 们 要 开发 的 是 一 个 Web 应 用 ， 并 且 导 和 人 了 专门 开发 Web 应 用 的 框 碟 ， 因 此 能 够 轻松 
实现 需求 山 在 Web 浏览 副 上 显示 、(D 经 由 网 络 使 用 以 及 (B® 同时 在 多 台 计 算 机 上 显示 。 

从 该 应 用 的 需求 来 看 ， 我 们 需要 的 功能 如 下 表 所 未。 




















说 明 
提交 留言 功能 | 显示 可 输入 名 字 和 留言 的 表单 ， 保 存 该 表单 发 送 的 数据 








留言 显示 功能 | 取出 提交 留言 功能 保存 的 数据 ( 优先 提交 日 期 较 新 的 数据 ) 并 显示 在 页 面 上 
Web 应 用 在 Web 浏览 器 上 显示 ， 并 且 可 让 多 人 台 计 算 机 同时 经 由 网 络 使 用 该 应 用 




















需求 (5) 是 与 页 面相 关 的 问题 ， 我 们 在 下 一 小 市 学 习 页 面 的 时 候 再 处 理 。 这 里 ,我们 再 确认 
一 包 已 明确 的 功能 ， 看 看 是 否 能 满足 需求 。 
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2.4.3 ”明确 必 备 的 页 面 
接 下 来 我 们 根据 应 用 的 功能 分 析 所 需 的 页 面 ， 结 果 如 下 。 





必 备 的 页 面 说 明 
提交 留言 功能 可 以 输入 名 字 和 留言 的 表单 可 供 输入 名 字 与 留言 的 栏 、 提 交 按 钮 














留言 显示 功能 显示 有 名 字 和 留言 的 下 表 在 页 面 上 列表 显示 已 提交 的 名 字 和 留言 








需求 中 提 到 整个 应 用 由 一 个 页 面 构成 (需求 (5) ),— MARERA PIT IRRE S I8]— 
个 页 面 中 。 于 是 ， 必 备 的 页 面 就 成 了 下 面 这 样 。 
必 备 的 页 面 页 面 元 素 
提交 和 显示 留言 的 页 面 可 以 输入 名 字 和 留言 的 表单 、 显 示 有 名 字 和 留言 的 列表 











至 此 ， 我 们 明确 了 必 备 的 页 面 。 接 下 来 可 以 开始 设计 页 面 了 。 


25 页面 设计 





需要 的 功能 和 页 面 都 已 经 敲定 ， 接 下 来 ， 我 们 就 动手 设计 页 面 吧 。 

至 于 为 什么 先 实现 页 面 而 非 功 能 ， 是 因为 当 页 面 完 成 后 ， 我 们 可 以 更 好 地 把 握 成 品 应 用 
的 整体 印象 。 在 把 功能 植 人 系统 之 前 ， 即 页 面 设计 阶段 ， 我 们 需要 先 写 好 HTML 文件 和 CSS 
文件 。 








2.5.1 确定 成 品 页 面 的 形式 


在 开始 编写 HTML 代码 之 前 ， 还 需 先 按 探 住 目 己 路 距 欲 试 的 心情 ， 把 我 们 希望 呈现 的 页 面 
明确 下 来 。 所 以 ， 现 在 要 做 的 就 是 把 必 备 页 面 转化 成 图 。 这 一 步 称 为 页 面 设计 。 

建议 各 位 先 在 纸 上 画 出 页 面 的 草图 。 如 果 和 希望 后 期 修改 起 来 方便 ， 或 者 希望 页 面 草 图 干净 
深 冠 ， 还 可 以 考虑 用 绘图 软件 或 页 面 设 计 方面 的 专业 软件 来 画 。 

这 次 我 们 没有 使 用 工具 ， 而 是 直接 画 了 一 张 页 面 草图 (图 2.2 )。 
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提交 留言 的 






EH 
TAF [提交 |] 提交 日 期 
aca oO] De E 
留言 记录 
ECET xxx 的 留言 ( 2011/10/01 --—- ) 
"i E 显示 提交 的 
d 内 容 


图 2.2 留言 板 应 用 的 页 面 草图 








按照 需求 ， 上 面 是 表单 ， 下 面 显示 提交 的 评论 内 容 。 另 外 ， 这 张 草 图 还 为 各 个 显示 元 又 
(表单 和 文章 ) 添加 了 注释 。 这 样 一 张 草图 不 但 能 在 植 入 功能 时 为 我 们 提供 参考 ， 还 能 随时 提醒 
我 们 仍 缺 少 哪些 功能 ， 这 对 开发 来 说 意义 重大 。 











2.5.2 编写 HTML 和 CSS 


下 面 我 们 开始 编写 HTML 文件 和 CSS 文件 。 为 了 查看 其 在 Web 浏览 器 中 的 效果 ， 我 们 将 
在 本 地 环境 ( 主 OS ) 中 进行 编写 。 编 写 完 成 的 文件 可 以 通过 scp 命令 发 送 到 服务 器 ， 以 便 后 续 
使 用 。 

首先 我 们 来 参考 草图 编写 HTML 文件 。 现 阶段 不 必 太 在 意 页 面 布局 ， 这 些 外 观 上 的 东西 都 
可 以 留 在 编写 CSS 文件 的 时 候 进行 调整 。 

LIST 2.7 是 我 们 编写 的 HTML 文件 的 源码 。 











& LIST 2.7 index.html 


«I!IDOCTYPE html- 
denen bete e UA quis 


«head» 
met eic cse o 
«title» E Ef </title> 
</head> 
<body> 
«hi1» 留言 板 </h1> 
<form action="/post" method="post"> 
«p» 请 留言 </p> 
<table> 
edm 
Elm E mie 
eres 


<input type="text" size="20" name="name" > 


E eres 

qs 

«tr 
«th» 留言 </th> 
«td 
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«textarea rows="5" cols="40" name-"comment"»«/textarea» 


c EG: 
db 
</table> 


«p»«button type-'submit"-» Æx «/button»«/p» 


</form> 
<div> 


<h2> 留言 记录 </h2> 


«h3» 3522€  EgEHES (2014/10/31 aa 0000 ae 


<p> 
8 EAS «br» 
留言 内 容 
</p> 
«ha» 游客 的 留言 (2014/10/31 09:00:00) :</h3> 
<p> 
8 EAS «br» 
8 eX 
</p> 
</div> 
</body> 
</html> 


用 Web 浏览 器 打开 这 个 HTML 文件 ， 结 果 如 图 2.3 所 示 。 


23 
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[3 
€ œ |5file:///C:/Users/tokibito/Desktop/index.html 


游客 ”的 留言 (2014/10/31 10:00:00) 


ES E 
piip oil 


游客 ”的 留言 2014/10/31 09:00:00) 


留言 内 容 
留言 内 容 





这 样 ，HTML 文件 就 写 好 了 ， 接 下 来 开始 写 CSS 文件 。 此 时 需要 调整 字体 大 小 、 颜 色 、 显 





示 位 置 等 外 观 ( 风 格 )。 
LIST 2.8 是 写 好 的 CSS 文件 。 


&J LIST 2.8 main.css 


body í( 
mangimi 
pagddgsmgescs 
colori OE ZI: 
background-color: 1004080; 
j 
Bi 
padding: 0 1em; 
color: EEEIEE E p 
j 
form | 
padding: 0.5em 2em; 
background-color: 1478B8F8; 


2.3 


只 有 HTML 文件 的 页 面 
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.main ( 
paddang: 05 
} 
.entries-area ( 
padding: 0.5em 2em; 
background-color: #FFFFFF; 
j 
.entries-area p { 
padding: 0.5em 1em; 
background-color: #DBDBFF; 


为 了 让 这 个 样式 表 和 生效， 我 们 需要 在 HTML 文件 中 添加 link 标签 读 取 CSS， 并 在 相应 位 置 
指定 class。 修 改 后 的 HTML 文件 如 LIST 2.9 所 示 。 





& LIST 2.9 index.html 


seo p latnu s 
celat tlie langs" za” s 
<head> 
<meta chaąarset="utf-8"> 


<title> MSI </title> 


<link rel="stylesheet" href="main.css" type="text/css"> <!-- Jl link ÎR --> 
</head> 
«body 


«hi1» 留言 板 </h1> 
<form action="/post" method="post"> 
«p» 请 留言 </p> 
<table> 
eu 
Eme Ze ce ipm 
gral 
<input type="text" size="20" name="name" > 
teres 
«f bus 
edo 
«th» 留言 </th> 
«b 
«textarea rows-z"5" cols-"40" name-"comment"»«/textarea» 
Asl 
</EES 
</table> 
«p»«button type-'"submit"-» ea «/button»«/p» 
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</form> 
«div class entries area! oo | fEdiv fr 73JUclassmETt --- 
<h2> 留言 记录 «/h2» 
<h3> 游客 的 留言 (2014/10/31 10:00:00) :</h3> 
«p 
dane bus 
sms 
</p> 
<h3> 游客 的 留言 (2014/10/31 09:00:00) :</h3> 
<p> 
& EDS «br» 
留言 内 容 
</p> 
e elk 
</body> 
</html> 


我 们 用 Web 浏览 器 打开 套用 CSS 后 的 HTML 文件 ， 如 图 2.4 所 示 。 


留言 记录 


3:9  B358 (2014/10/31 10:00:00) 


3:9  B358z:(2014/10/31 09:00:00) 


留言 内 容 
留言 内 容 





24 套用 CSS 后 的 页 面 
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这 样 我 们 就 写 好 了 显示 页 面 用 的 HTML 文件 和 CSS 文件 。 现 在 用 scp 命令 将 已 写 好 的 文 
件 发 送 到 VirtualBox 上 的 Ubuntu 环境 下 。 发 送 文 件 的 命令 如 LIST 2.10 所 示 。 
Ə LIST 2.10 用 scp 命令 发 送 文件 


S$ Sa = 2222 lndex, neml maln. ee Jacoore@l27.0.0.1: 
NOTE 
SSH 连接 的 设置 等 问题 请 参考 附录 Bo 


下 一 步 我 们 要 实现 功能 ， 并 将 其 植 人 页 面 中 。 


2.6 ”实现 功能 





Ab 
HE 











终于 到 了 编写 Python 程序 的 阶段 。 我 们 准备 让 服务 
。 这 里 将 优先 实现 比较 重要 的 功能 ， 或 者 能 


HE x 


fiir Jg 
提高 


的 程序 来 实 
JE [r3] 
保存 和 读 取 用 户 提交 的 数据 是 这 个 应 用 的 核心 部 分 ， 所 以 我 们 先 从 它 下 手 。 
2.6.1 保存 留言 数据 





DAS; 
其 他 部 分 实现 速度 的 功 





岗 这 个 应 用 的 必 备 功 
能 。 


提交 功能 不 但 要 能 保存 表单 传 来 的 名 字 和 留 
示 时 使 用 。 





e es 
一 一 


三 











， 还 得 能 将 提交 日 期 及 时 间 存 储 下 来 ， 供 显 
Vx 
写 留言 
代码 如 LIST 2.11 所 示 。 


这 里 我 们 用 Python 的 标准 模块 shelve 来 存储 数据 。shelve 能 够 像 Python 字典 对 象 一 样 操作 
个 字典 ， 然 后 将 这 些 字 典 保存 在 shelve 中 。 

下 面 来 编写 

© LIST 2.11 


guestbook.py 
# coding: utf-8 


Zi. KATRA.. Wi, shelve 会 将 提交 的 数据 转换 成 字典 对 象 ， 以 列表 形式 保存 多 


import shelve 


DATA FILE = 


板 的 脚本 文件 。 guestbook.py 实现 了 负责 保存 数据 的 save data PRA, 具体 


'guestbook.dat' 
def save data (name, 
ZEE REZ NAGE 


comment 


create at): 
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# 通过 shelve 模块 打开 数据 库 文件 
database = shelve.open(DATA FILE) 
# 如 果 数 据 库 中 没有 greeting 1ist， 就 新 建 一 个 表 
iE "greeting ligt! mogt in detabase: 
greeting list = [] 
else: 
# 从 数据 库 获 取 数 气 
greeting list = Catabase |" greeting List] 
# 将 提交 的 数据 添加 到 表 头 
greeting list.insert(0, | 
'name': name, 
'comment': comment, 
leregte aut; crestecat, 
) 
# 更 新 数据 库 
dacdbugscMenccc cM cU ee se 
# 关闭 数据 库 文件 


database.close() 


然后 再 来 看 看 save data 吨 数 的 运行 情况 。 我 们 通过 终端 在 guestbook.py 文件 所 在 的 目录 下 
启动 Python shell， 然 后 像 LIST 2.12 这 样 通过 Python shell 加 载 并 执行 guestbook 模块 的 save - 
data PK. 


© LIST 2.12 save data 函数 的 运行 测试 
S ls d i guestbook. py VT a 下 
guestbook.py 
$ python & /Bz)Python shell 
>>> import datetime 
>>> from guestbook import save data 
>>> aye Carta i MC qM DUM 


datetime.datetime(2014, 10, 31, 10, 0, 0)) 


这 里 我 们 将 datetime 模块 的 日 期 时 间 对 象 传递 给 传 值 参 数 create_at， 以 此 来 保存 提交 的 日 
期 和 时 间 。 在 这 个 阶段 ， 我 们 只 能 看 出 它 的 运行 是 否 报错 ， 至 于 数据 是 不 是 真 的 被 保存 下 来 了 ， 
还 要 等 取出 数据 的 功能 实现 之 后 才能 知道 

















2.6.2 ”获取 已 保存 的 留言 列表 


实际 上 ， 我 们 在 保存 数据 的 时 候 就 从 shelve 模块 中 取出 过 数据 ， 现 在 只 把 这 部 分 代码 单独 
拿 出 来 做 成 函数 即 可 。 
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在 guestbook.py "FH Z3JIIl load data PEZ ( LIST 2.13 )。 


© LIST 2.13 guestbook.py 


dere easdadatou e 
""" 返回 已 提交 的 数据 
# 通过 shelve 模块 打开 数据 库 文件 
database = shelve.open(DATA FILE) 
# 返回 greeting 1ist。 如 果 没 有 数据 则 返回 空 
greeting list = database. get (' greeting liste", []) 
database.close() 


return greeting Ligt 


这 里 同样 通过 Python shell 查看 其 运行 情况 。 局 动 Python shell, WMO ZÍT ( LIST 
2.14); 


© LIST 2.14 load data 函数 的 运行 测试 
>>> From gUesToook import load) data 
>>> load. eene t) 
[{'comment': 'test comment', 'name': 'test', 'create at': datetime.datetime d 


(C20 Ta 0 I SLOPE Le 





如 末 运 行 正常 ， 那 就 表示 我 们 能 获取 save data RURE P RKI o 


2.6.3 ”用 模板 引擎 显示 页 面 


从 文件 中 取出 数据 之 后 ， 为 了 将 其 显示 到 页 面 上 ， 我 们 要 使 用 模板 引擎 。 模 板 引 擎 可 以 将 
模板 FEF WIJE ) 与 要 植 人 模板 内 的 数据 合并 输出 。Flask 标准 文 持 Jinja2 模板 引擎 。 

接 下 来 创建 templates 目录 ， 然 后 将 前 面 已 经 写 好 的 HTML 文件 放 到 该 目录 下 C LIST 2.15 )。 
这 样 一 来 ， 我 们 就 可 以 以 它 为 模板 生成 HIML To 











© LIST 2.15 ”放置 模板 


$ mkdir templates 
$ mv index.html templates/ 





下 面 从 程序 问 入 手 ， 用 这 个 HTML 文件 (模板 ) 来 完成 页 面 的 显示 。 先 添加 代码 ， 让 
guestbook.py 调用 Flask， 然 后 再 添加 用 来 显示 首页 的 图 数 以 及 用 来 局 动 Web 服务 天 的 代码 
(LIST 2.16 )。 
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加 LIST 2.16 guestbook.py 


u Coding: uti-=-8 


import shelve 

rrom flask Import Flask, sees. render cemplate, redirect, escape, Markup 
appllicstione-Riass e) 

DATACPEILE — 'gquesutbookvdat' 


def save datal(lname, comment, create at) : 


"un 保存 提交 的 数据 


# 省 略 


def load data(): 
"n" jk [n] 已 提交 的 数据 


# 省 略 


Gapplication.route('/') 


def index(): 


"nnn AA 
使 用 模板 显示 页 面 


rectum render cemplate (' ince. memi" ) 


itf name _ == ' maim  ': 
# 在 IP 地址 127.0.0.1 的 8000 端口 运行 应 用 程序 
appibrecatron.bcun(' 1272095051775 98000 cdebudg-True) 


我 们 将 Flask 类 的 实例 赋 给 变量 application， 传 值 参 数 指定 为 | name 变量 的 模块 名 。 方 
法 route 是 一 个 闻 饰 希 ， 负 责 注 册 针 对 特定 URL 执行 的 函数 。 这 里 我 们 让 主页 的 URL 对 应 执行 
index 图 数 。render template 困 数 负责 将 指定 文件 用 作 模 板 ， 再 通过 模板 引擎 进 行 输出 。 

Flask 类 的 run 方法 用 于 启动 Web 服务 融 并 执行 应 用 程序 ， 传 值 参数 用 来 指定 要 绑 定 的 IP 
地 址 及 端口 。 男 外 ， 将 debug 选项 指定 为 True 时 , 一旦 应 用 程序 出 错 ，Web 浏览 硕 关 就 会 局 
动 可 用 的 调试 程序 。 

接 下 来 用 python 命令 运行 guestbook.py(LIST 2.17 )。 























B LIST 2.17 运行 已 开发 完毕 的 Web 应 用 


$ python guestbook.py 
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2 Rumning on nEO /27.0.0.128000/ 


* Restarting with reloader 


运行 guestbook.py 之 后 ， 在 该 环境 的 (这 里 是 VirtualBox 上 的 Ubuntu ) 127.0.0.1 地 址 的 
8000 端口 等 待 请 求 的 应 用 服务 带 ( Web IREKE) 就 会 局 动 。 我 们 可 以 在 终端 同时 按 下 Ctrl 键 和 
CH, KAITARA Ao 

现在 我 们 需要 设置 好 8000 端口 的 端口 转发 ， 然 后 在 Web 浏览 器 中 打开 http://127.0.0.1:8000/; 
如 何 ， 看 到 页 面 没有 ? 

我 们 会 发 现 CSS 文件 并 没有 生效 ， 所 以 需要 重新 调整 一 下 CSS 文件 的 位 置 ， 让 它 能 够 被 读 
Wo Flask 会 公开 static 目录 下 存放 的 静态 文件 。 接 下 来 我 们 创建 一 个 static 目录 ， 把 main.css X 
件 放 进 去 ( LIST 2.18 )。 











E LIST 2.18 放置 静态 文件 


S$ mkdir static 


S mv maeumecss statuo 





另外 ， 还 要 将 templates/index.html 中 的 CSS 文件 引用 位 置 改 为 /static/main.css ( LIST 2.19, 
LIST 2.20 )。 


© LIST 2.19 templates/index.html ( 更 改 前 ) 


«link rel="stylesheet" href-"main.css" type="text/css"> 


Ej LIST 2.20 templates/index.html ( Æ KJE ) 


<link rel="stylesheet" href="/static/main.css" type="text/css"> 





现在 再 用 Web 浏览 器 打开 该 页 面 ， 就 会 发 现 CSS 文件 这 时 已 经 生效 了 。 
接 下 来 ， 我 们 把 从 数据 库 中 取出 的 内 容 显示 在 页 面 上 上。 修改 guestbook.py 文件 ， 让 index PR 
数 调 用 load data 晒 数 ， 同 时 使 模板 能 够 使 用 load data 晒 数 取出 来 的 数据 ( LIST 2.21 )。 








© LIST 2.21 guestbook.py 


Gapplication.route('/') 


def index(): 


"nnn Eu 
使 用 模板 显示 页 面 


# 读 取 已 提交 的 数据 
greeting listr = load! ceta () 


return render en ("index McmLl', greeting list=greeting Ligt) 


render template 函数 可 以 将 关键 字 传 值 参 数 所 指定 的 信用 作 模 板 变 量 。 比 如 本 例 就 使 用 了 
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名 为 greeting list 的 模板 变量 。 
此 外 ， 我 们 还 要 修改 模板 templates/index.html， 使 其 能 够 使 用 模板 变量 进行 显示 。 现 在 对 
HTML 中 的 显示 留言 部 分 作 如 下 修改 ( LIST 2.22 )。 





© LIST 2.22 templates/index.html 
Eon msc co dqequ 

«h2» 留言 记录 «/h2» 

($ for greeting in greeting list %} 
<h3>{{ greeting.name }} 

的 留言 ({{ greeting.create at }}):</h3> 

<p>{{ greeting.comment }}</p> 

(* endfor £) 


</div> 
模板 内 可 以 使 用 一 种 特殊 的 描述 方式 ， 即 模板 语言 。Jinja2 的 模板 可 以 通过 {%…%}) 的 形式 
使 用 证 或 for 等 控制 语句 。 植 人 有 模板 变量 的 部 分 用 {{…}} 的 形式 描述 。 在 上 述 模板 中 ， 程 序 
会 从 greeting list 中 逐一 取 值 并 赋 给 模板 变量 greeting， 然 后 使 用 从 for 到 endfor 之 间 的 模板 变 
量 进行 循环 输出 。 
这 样 一 来 ， 应 用 就 能 将 save data 果 数 保存 的 数据 显示 在 页 面 上 了 。 








2.6.4 准备 评论 接收 方 的 URL 


下 一 步 我 们 用 save data 函数 保存 表单 提交 来 的 数据 。 由 于 模板 文件 中 表单 的 action 值 为 / 
post， 所 以 我 们 就 做 出 这 个 URL. 
这 里 ， 我 们 将 post 函数 添加 到 guestbook.py 的 if_ main ... 前面 (LIST2.23 ). 











© LIST 2.23 guestbook.py 


Gapplication.route('/post', methods-['POST']) 
def post(): 
""" 用 于 提交 评论 的 URL 


# 获取 已 提交 的 数据 


name = request.form.get('name') # 名 字 
comment = request.form.get('comment') # 留言 
create at = datetime.now() 4 投稿 时 间 ( 当前 时 间 ) 
# 保存 数据 


save data (neme, Comment, Create at) 
# 保存 后 重 定向 到 首页 


到 SEE raedireoae aA) 
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在 Flask 中 ， 可 以 用 request.form 引用 表单 发 来 的 数据 。 此 外 ， 由 于 保存 数据 后 需要 重新 显 
示 首 页 ， 所 以 我 们 要 返回 redirect 困 数 的 结果 并 进行 重 定 回 。 

post 函数 使 用 了 datetime 模块 ， 所 以 需要 在 文件 开头 添加 如 LIST 2.24 所 示人 代码， 以 导入 该 
RER o 


EJ LIST 2.24 导入 datetime 模块 ( guestbook.py ) 
# coding: utf-8 
import shelve 


from daretime import daretime # IMET 





至 此 ， 保 存 数 据 的 功能 也 实现 了 。 应 用 的 运行 部 分 基本 完工 。 


2.6.5 ”调整 模板 的 输出 


程序 运行 所 需 的 功能 现在 已 经 基本 上 属实 现 了 ， 但 这 里 至 少 还 有 两 点 需要 注意 。 











。 表 单 提交 多 行 留言 时 ， 无 法 正常 显示 留言 
。 显 示 的 时 间 精 确 到 了 毫秒 





要 想 解决 这 两 个 问题 需 创 建 一 个 模板 过 滤 融 。 模 板 过 滤 融 会 对 模板 变量 的 值 加 以 转换 并 输 


出 。 接 下 来 ， 我 们 在 guestbook.py BJ i£ _ main  .. .前 添加 如 LIST 2.25 所 示人 代码 ， 将 模板 
TUE dg P ACER 


© LIST 2.25 guestbook.py 
Capplication,. template Filter it Umen ) 
cef nl2lbr filter(s): 
"n" 将 换行 符 置换 为 pr 标签 的 模板 过 滤器 


return escape(s).replace('WMn', Markup ('<br>')) 


CGapplication,. template use t datetime Eme") 
cet leue sts fme eet db ert (CEt) s 


""" f datetime 对 象 更 容易 分 辨 的 模板 过 滤器 


return dt.strftime('£Y/£m/$d $£H:£2M:$S') 





Flask 类 的 template filter 7r i i&— dwell, E f Ti REEDE Et PRBRPEROBUGSE UE AN o 
REFP3eTHE, TRAE P EDBOGEUE a8 TRUDUSE t ZR E RBA RUR I THO. KZ, T BRUCH XR E 
值 则 为 最 后 输出 的 值 。 在 上 述 源码 中 ， 我 们 注册 了 nl2br 和 datetime fmt P9 T-ESBOSEUS $8 o 

接 下 来 ， 我 们 修改 一 下 templates/index.html 文件 ， 让 模板 能 够 使 用 这 两 个 模板 过 小 大 ( LIST 2.26 )。 
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© LIST 2.26 templates/index.html 


«div class-"entries-area"- 
<h2> 留言 记录 «/h2» 
($ for greeting in greeting list %} 
<h3>{{ greeting.name }} 
的 留言 ({{ greeting.create at|datetime fmt ]]):«/h3» 
<p>{{ sgreeting.comment|nl2br }}</p> 
(* endfor %) 


</ ciu 
TETUR PAS E b EUE a TJZRAARÍBIER, HrSERERSOBUSS EUR E EAT [^ 3 
模板 过 滤 锅 名 即 可 。 在 本 次 的 模板 中 ， 我 们 给 greeting.create at 指定 了 datetime fmt xL UE ss, 
greeting.comment 指定 了 nl2br i3 JE kF o 
至 此 ， 服 务 希 端的 功能 、 功 能 与 页 面 的 对 接 已 经 全 部 完工 。 从 Web 浏览 需 看 到 的 效果 如 图 
2.5 所 示 。 显 示 留 言 部 分 ”显示 了 我 们 已 提交 的 内 容 。 


留言 记录 
测试 人 ”的 留言 2014/10/31 16:39:07) 


提交 内 容 

第 2 行 

第 3 行 

tokibito 的 留言 (2014/10/31 16:38:48) 
你 好 ! 你 好 | 

tokibito 的 留言 (2014/10/31 10:00:00) 


test 的 留言 





2.5 植 入 功能 后 的 页 面 


(D 言 记 录 部 分 的 tokibito 为 本 章 撰写 者 冈 野 真 也 先生 的 Twitter 用 户 名 。 一 一 编者 注 
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dc 
ri 


看 成 品 


个 应 用 的 开发 过 程 到 这 里 就 结束 了 ， 接 下 来 就 是 确认 该 应 用 的 运行 是 否 正常 ， 以 及 看 一 
是 否 能 满足 我 们 当初 定 下 的 知 求 。 





2.7 ”查看 运行 情况 











虽然 程序 的 编写 已 经 结束 ， 但 我 们 还 需要 确认 应 用 程序 能 不 能 按 预 想 的 样子 运行 。 下 面 
束 来 逐条 确认 刚刚 开发 完成 的 应 用 是 否 满足 知 求 ， 以 及 运行 上 是 否 存 在 问题 。 到 了 这 一 步 ， 
可 能 会 有 人 和 觉得 “开发 的 时 候 就 已 经 辽 条 确认 过 了 ， 肯 定 不 会 有 问题 的 "。 这 种 心情 可 以 理 
解 。 但 要 知道 ， 我 们 在 编码 后 期 阶段 所 作 的 修改 可 能 会 导致 之 前 的 功能 出 现 Bug， 而 且 也 难 
保 开 发 过 程 中 不 会 遗漏 菏 些 需求 。 因 此 要 想 制作 一 个 品质 上 乘 的 应 用 程序 ， 这 项 确认 工作 必 
不 可 少 。 

好 了 ， 现 在 让 我 们 回顾 一 下 这 个 留言 板 应 用 的 需求 。 




















D E Web 浏览 各 上 显示 一 个 包含 “提交 留言 ”表单 的 页 面 

可 以 在 提交 留言 表单 中 输入 名 字 和 留言 正文 

O 通过 提交 留言 表单 发 送 的 名 字 和 留言 内 容 会 被 保存 

由 已 保存 的 名 字 、 留 言 、 提 交 日 期 会 显示 在 页 面 中 

C) 整个 应 用 由 一 个 页 面 构成 ， 页 面 上 部 为 提交 留言 表单 ， 下 部 显示 已 提交 的 内 容 
© 提交 的 内 容 按 新 旧 顺 序 由 上 到 下 排列 

CD 可 经 由 网 络 (互联 网 ) 使 用 本 系统 

(8 可 同时 在 多 台 计 算 机 上 显示 已 提交 的 内 容 












































现在 运行 开发 服务 硕 ， 碍 看 成 品 是 否 能 满足 这 8 项 需求 。 

只 要 通过 Web 浏览 器 访问 http://127.0.0.1:8000/ 即 可 查看 需求 四 是 否 得 到 了 满 
足 。 与 此 同时 ， 由 于 虚拟 机 和 本 地 计算 机 之 间 经 由 网 络 连 接 ， 所 以 和 @@ 也 没有 问题 。 至 于 
四 ， 只 要 我 们 能 在 页 面 中 的 表单 里 填写 名 字 和 留言 内 容 ， 那 就 是 过 关 了 。 接 下 来 输入 内 容 并 
点 击 提交 按钮 ， 随 后 页 面 被 刷新 ， 刚 刚 提交 的 内 容 显 示 在 了 页 面 上 。 于 是 () 也 搞定 了 。 然 后 
重启 开发 服务 器， 再 次 通过 Web 浏览 需 读 取 页 面 ， 如 果 之 前 提交 的 内 容 能 够 正常 显示 ， 就 表 
示人 和 个 也 OK。 最 后 我 们 再 进行 一 次 输入 和 提交 ， 只 要 后 来 提交 的 内 容 显示 在 最 上 方 ， 那 么 
需求 (@) 也 就 满足 了 。 

男 外 ， 这 次 我 们 开发 的 应 用 没有 对 使 用 者 输入 的 字符 串 做 任何 限制 ， 而 且 输 入 的 内 容 会 直 
接 以 植 人 HTML 的 形式 显示 出 来 。 因 此 ， 接 下 来 需要 确认 是 否 存 在 跨 站 脚本 攻击 漏洞 。 





O 
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NOTE 

跨 站 脚本 攻击 ( Cross Site Scripting, XSS”) 是 一 种 常见 的 漏洞 ， 用 户 能 在 某 些 以 植 入 
HTML 的 形式 显示 输入 内 容 的 应 用 中 ， 故 意 植 入 一 些 攻击 型 的 脚本 (比如 HTML 标签 或 
JavaScript 等 )。 

XSS 漏洞 可 被 用 在 会 话 支持、 钓鱼 等 恶意 行为 上 。 


要 验证 应 用 中 是 否 含有 XSS 漏洞 ， 只 需要 像 LIST 2.27 这 样 ， 在 留言 输入 栏 中 键入 带 有 
JavaScript 代码 的 HTML 标签 ， 然 后 点 击 提 交 即 可 。 


© LIST 2.27 ”验证 跨 站 脚本 攻击 时 需要 输入 的 内 容 


<script>alert ('NG')</script> 





显示 提交 内 容 的 区 域内 是 否 显示 出 了 我 们 输入 的 字符 串 呢 ?如 果 该 应 用 含有 XSS d. 3D 
么 NG FEER WR TED dE HE IE 

我 们 在 本 次 开发 中 使 用 的 是 Jinja2 模板 引擎 ， 它 在 翻译 字符 串 时 会 日 动 忽略 HTML 标签 的 
“< 和 >” 和 符号。 因此， 我 们 的 应 用 能 够 成 功 避 免 XSS 漏洞 。 

建议 各 位 在 最 后 查看 运行 情况 时 也 检测 一 下 其 他 可 能 造成 安全 问题 的 漏洞 。 














NOTE 

与 XSS 同样 恶名 昭彰 的 漏 泪 还 有 跨 站 请 求 伪造 ( Cross Site Request Forgery，CSRF )。 用 
户 通过 与 目标 应 用 程序 无 关 的 外 部 输入 表单 ( 这 些 输入 表单 通常 用 于 攻击 ) 发 送 数 据 ， 一 旦 目标 
应 用 程序 处 理 了 这 些 数据 ， 就 会 引发 使 用 者 意料 之 外 的 操作 。 

CSRF 漏洞 可 被 用 来 触发 使 用 者 意料 之 外 的 操作 ( 比如 在 线 购买 商品 、 泄 圳 个 人 信息 等 )。 

本 章 中 开发 的 应 用 并 疫 有 对 CSRF Tw. HF XSS 和 CSRF 这 两 种 攻击 手法 可 以 相互 
组 合 出 新 的 攻击 手法 ， 所 以 建议 各 位 务必 做 好 防范 工作 。 


如 果 上 述 过 程 全 部 顺利 通过 ， 我 们 的 应 用 开发 就 可 以 宣告 完工 上 了 。 各 位 羊 吉 本。 
最 终 的 文件 结构 如 下 表 所 示 。 


文件 路 径 说 明 


guestbook.py 服务 器 程序 
guestbook.dat 提交 数据 文件 











(D Cross Site Scripting 的 缩写 为 XSS， 这 是 为 了 和 层 党 样式 表 (Cascading Style Sheet, CSS ) 有 所 区 分 。 
一 编 省 注 
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文件 路 径 ij 


static/main.css CSS 文件 
templates/index.html 输出 HTML 的 模板 ， 用 于 显示 提交 /留言 列表 页 面 











2.8 ”小结 














Web 应 用 开发 的 第 一 步 是 确定 自己 要 开发 什么 东西 。 要 是 对 自己 要 做 的 东西 没有 概念 ， 开 
发 就 不 可 能 进行 下 去 。 另 外 ， 如 果 必 备 的 页 面 和 功能 不 够 明确 ， 那么 编写 代码 的 过 程 将 是 相当 
痛 蔡 的 。 要 想 让 开发 如 行云流水 般 流畅 ， 那 就 必须 将 这 些 不 确定 的 因素 统统 明确 下 来 ， 确 定 一 
A3T ACUIUEE « 

在 本 章 中 ， 我 们 强调 了 Web 应 用 是 一 个 发 送 动 态 内 容 的 程序 ， 并 且 用 户 可 以 经 由 Web 浏览 

— 同时 还 学 习 了 Web N iz / Hits MAZER EP. 235b, RiT 

以 留言 板 应 用 为 例 ， 从 确定 需求 到 最 终 完 成 ， 边 学 边 练 地 一 起 了 解 了 整个 应 用 开发 流程 。 本 

AAEE, 











9B 339 Python 项 目的 结构 与 包 的 创建 


在 Python 圈子 里 ， 有 许多 开发 者 会 无 偿 公 开 上 自己 开发 的 程序 库 。 为 了 让 使 用 者 能 够 通过 
pip 命令 安装 这 些 库 ， 我 们 在 发 布 时 需要 将 其 创建 成 一 种 特殊 的 文件 ， 这 种 文件 就 是 程序 包 。 在 
使 用 Python 语言 进行 开发 的 过 程 中 ，Python 目 帘 的 库 往 往 不 能 满足 我 们 ， 因 此 我 们 还 需要 用 到 
这 些 程序 包 。 

本 章 将 介绍 程序 包 的 制作 流程 。 首 先 ， 我 们 要 了 解 一 下 Python 项 目 开 发 环境 的 相关 工具 。 
然后 ， 我 们 来 了 解 一 下 该 环境 下 的 相对 多 于 擎 握 的 Python 项 目 目录 结构 以 及 文件 结构 ， 同 时 对 
第 2 章 中 开发 的 留言 板 应 用 进行 整理 ， 封 装 成 色 。 最 后 还 将 学 习 如 何 将 我 们 开发 的 项 目 发 布 在 
PyPI E, FETAI Fe 























3.1 Python 项 目 





H Python 开发 的 应 用 程序 达到 一 定 规模 后 ， 必 人 然 会 出 现 多 个 模块 ( .py ) 或 程序 包 目 录 。 同 
时 除 源 码 以 外 ， 说 明 性 质 的 文本 文件 、 管 理 相关 程序 库 的 元 信息 等 部 会 越 来 越 多 。 这 些 为 同一 
个 目的 服务 的 文件 、 目 录 以 及 元 信息 ， 就 是 我 们 所 说 的 项 目 。 

实际 上 ，Python 项 目的 内 部 结构 是 因 项 目 而 异 的 。 这 里 ， 一 个 完整 的 结构 震 要 满足 以 下 
F 


























e 拥有 一 个 在 版 本 管理 之 下 的 源码 目录 
。 程序 信息 在 setup.py 中 定义 
e 在 一 个 virtualenv 环境 中 运行 





对 于 Python 开发 上 的 一 些 约定 俗 成 的 工具 来 说 ,满足 上 述 条 件 的 结构 更 便于 人 处理 。 我 们 在 
章 中 介绍 的 pip 和 virtualenv 都 属于 这 类 工具 。 
这 些 Python 中 的 约定 俗 成 的 工具 也 随 春 时 代 逐 渐变 化 肴 。 近 年 来 PEP 标准 正 被 逐渐 推行 。 
为 了 规范 这 些 约定 俗 成 的 东西 ，2013 年 成 立 了 PyPA (Python Packaging Authority ) 工作 组 。 
PyPA 负责 Python 封装 方面 相关 工具 的 维护 ， 以 及 PEP 标准 化 等 工作 。 许 多 老 脾 的 封装 相关 工 
具 都 被 移交 给 PyPA 管理 ， 包 括 本 书 中 使 用 的 pip、virtualenv、wheel 现在 也 都 由 PyPA 提供 。 
如 今 ， 许 多 Python 项 目的 结构 都 以 PyPA 提供 的 工具 为 参照 ， 选 用 了 适合 这 些 工具 的 文件 、 
日 录 结 构 。 
如 采 项 目的 结构 符合 标准 ， 那 么 它 与 工具 之 则 就 会 有 很 强 的 亲和力 ， 而 且 便 于 今后 自己 或 
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第 3 章 Python 项 目的 结构 与 包 的 创建 | 49 


其 他 开发 者 进一步 开发 。 男 外 ， 本 章 中 介绍 
适用 于 团队 的 开发 环境 。 








的 结构 与 流程 不 但 适用 于 个 人 的 开发 环境 ， 同 样 也 


NOTE 


在 PyPA 的 封 狐 文档 中 ， 将 以 发 布 为 目的 的 一 个 整体 单位 称 为 一 个 项 目 ( Project )。 


https://packaging.python.org/en/latest/glossary.htmltdtterm-project 


3.2 ”环境 与 工具 


本 市 ， 我 们 将 对 Python 项 目 开 发 的 必 备 工具 进行 了 解 。 此 外 ， 还 将 学 习 项 目的 目录 结构 、 
必 有 备 程 序 包 的 管理 方法 以 及 安装 方法 。 


3.2.1 用 virtualenv 搭建 独立 环境 








如 采 大 量 项 目 全 都 混杂 在 一 个 环境 下 ， 程 序 很 可 能 会 在 预想 不 到 的 地 方 停 止 运行 ， 而 且 不 
利于 我 们 把 握 当 前 环境 的 具体 状态 。 所 以 为 了 防止 出 现 这 些 恼人 的 情况 ， 我们 建议 各 位 搭建 简 
单 的 独立 环境 。 

使 用 virtualenv 可 以 给 每 个 项 目 搭建 一 个 独立 的 Python 环境 。 

独立 环境 有 以 下 优点 。 


。 添加 程序 包 以 及 杰 更 版 本 时 ， 能 将 影响 控制 在 当前 环境 内 

。 便于 判断 已 安 猴 的 程序 包 是 否 可 以 删除 

e 不 再 需要 该 环境 时 ， 可 以 二 接 删 除 整 个 环 踪 

e 一 旦 出 了 问题 ， 那 么 问题 必然 出 在 该 环境 的 项 目 上 ， 这 就 有 助 于 我 们 找 出 问题 所 在 





@, virtualenv 


NOTE 
in LA Z3 virtualenv 1.11.65 
用 pip 安装 外 部 程序 库 时 ， 该 库 会 被 安装 到 Python 的 安装 目录 下 。 比 如 Python 是 安装 在 了 


/ust/local/ 目录 下 ， 那 么 该 外 部 程序 库 就 会 被 安 猴 在 /usr/local/lib/python2.7/site-packages 目录 下 ， 
这 就 是 库 的 默认 安 疙 路 笃 。 但 这 样 一 来 ,不 同 目 的 的 程序 库 就 全 都 安 污 到 了 同一 日 录 下 ,不 但 
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容 多 导致 版 本 神 突 ， 而 且 很 难 分辨 出 哪些 程序 库 已 经 没 用 了 。 

另外 ,在 /usr/local/ 下 安 猴 东西 时 ， 需 要 我 们 提供 该 目录 的 写 和 人 权限。 我 们 对 目 己 的 计算 机 
中 的 OS 目录 具有 写 人 权限 ， 但 是 不 一 定 对 其 他 计算 机 的 OS 目录 也 拥有 写 入 权限 。 就 算 有 ， 乱 
用 权限 也 很 容 多 导致 意外 事故 ， 因 此 应 尽量 避免 乱用 权限 。 

其 实 ， 这 些 问题 都 可 以 用 virtualenv 解决 。 

virtualenv 的 主要 特征 体现 在 下 列 功能 








e 在 virtualenv 环境 中 可 月 由 安装 Python， 不 需要 提供 OS 管理 员 权 限 
e jt virtualenv 环境 下 ， 可 根据 目的 不 同 来 安装 程序 库 ， 这 样 一 来 包 的 安装 目的 和 依存 关系 








束 会 更 加 明确 
e 仍然 使 用 Python 主体 ， 且 虚拟 环境 仅 由 一 小 部 分 备份 文件 构成 ， 因 此 环境 搭建 速度 快 ， 
占用 便 盘 空间 小 





e 无 视 Python 主体 的 site-packages， 而 且 能 分 离 主体 上 已 安装 完毕 的 程序 包 
e HJ 以 用 activate/deactivate 命令 随时 启动 /关闭 virtualenv 环境 


virtualenv 命令 可 以 将 任意 目录 设置 为 “virtualenv 环境 (Python HE ARS). WMA 
virtualenv 环境 之 后 ，Python 解释 需 会 将 该 目录 识别 为 默认 安装 目录 。 所 以 ， 如 采 我 们 此 时 用 
pip 命令 安装 程序 库 ， 那 么 这 个 程序 库 将 被 安装 到 virtualenv 环境 中 。 

下 面 我 们 来 了 解 一 下 virtualenv 的 一 般 使 用 方法 以 及 一 些 浓 用 选项 。 其 他 详细 知识 请 参考 以 
下 网 站 。 











Reference Guide - virtualenv 1.11.6 documentation 


https://virtualenv.pypa.io/en/latest/ 





Python 标 配 的 用 户 站 点 目录 功能 与 virtualenv 的 差异 

用 户 站 点 目录 功能 由 PEP 370 提出 ， 随 后 被 Python 采纳 并 从 Python 2.6 版 本 开始 提供 。 
这 个 功能 让 Python 解释 器 能 够 识别 安装 在 用 户 目 录 $HOME/.local 下 的 程序 库 。 与 此 同时 ，pip 
也 纳入 了 这 一 机 制 ， 人 允许 用 户 使 用 --user 选项 将 程序 库 安 装 到 $HOME/.local 目录 下 。 

有 了 这 个 功能 之 后 ， 用 户 不 必 使 用 virtualenv 就 能 自由 地 安装 程序 库 。 不 过 ， 用 户 站 点 目录 
功能 无 法 像 virtualenv 一 样 搭 建 多 个 环境 ， 上 自然 也 就 不 能 在 多 个 环境 中 切换 。 


(D nttps://www.python.org/dev/peps/pep-0370 
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€ virtualenv 的 使 用 方法 
接 下 来 我 们 看 一 看 virtualenv 的 安装 、virtualenv 环境 的 搭建 以 及 启动 (LIST3.1、LIST3.2 )。 


e LIST 3.1 安装 virtualenv 


$ sudo pip install virtualenv 


加 LIST 3.2 virtualenv 环境 的 搭建 及 启动 


$ cd /home/bpbook/work 

S$ virtualenv venv 

$ ls -F 

venv/ 

$ source venv/bin/activate 


(venv)S$ 


如 上 所 示 ， 使 用 某 一 virtualenv 环境 的 activate 命令 后 ， 该 virtualenv 环境 就 会 被 设置 为 
默认 的 Python 执行 环境 。 这 里 我 们 搭建 了 名 为 venv 的 virtualenv 环境 ， 因 此 命令 提示 符 前 会 出 
现 环 境 名 (venv) 

执行 activate 后 ，PATH、PROMPT 等 数 个 环境 变量 会 被 改写 。 这 样 一 来 ， 对 象 
virtualenv 环境 的 bin 目录 将 在 PATH 搜索 中 被 优先 处 理 。 此 时 ， 只 有 环境 变量 会 被 修改 ， 文 件 
并 不 会 有 任何 变动 。 

在 这 个 状态 下 ,计算 机 会 优先 使 用 venv/bin 目录 下 的 执行 文件 来 执行 各 个 命令 。 给 
virtualenv 环境 安装 额外 的 程序 库 时 ， 我 们 需要 如 LIST 3.3 所 示 ， 在 命令 提示 符 前 有 “ (venv)" 
的 状态 下 执行 pip 命令 。 





E LIST3.3 给 virtualenv 环境 安装 程序 库 


(venv)$ pip install requests bottle 
(venv)$ pip freeze 
bottle==0,12.7 


redquestes-2.42.5 


如 果 要 使 用 这 个 virtualenv 环境 的 Python， 则 要 执行 该 virtualenv 环境 的 python 命令 
( LIST 3.4 )。 


© LIST 3.4 运行 virtualenv 环境 的 Python 
(venv)$ python 
Byeneon 2.7.6 (default, Mar 22 2014, 22:59:56) [GCE 4.8.2] on tame 
mpe "help". "copyright", "credrts" or "license" ror more rxntormatrjon. 
>>> import sys 


>>> SyS.executable 
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' /home/bpbook/work/venv/bin/python!' 
>>> import requests 


>>> umport bottle 





解除 activate 时 ， 需 要 还 原 之 前 被 activate 更 改 的 环境 变量 。 因 此 我 们 要 结束 shell, 
或 者 执行 deactivate 命令 (LIST 3.5 ), 


E LIST 3.5 通过 deactivate 命令 关闭 virtualenv 环境 


(venv)s deactivate 
$ python -c "import sys; print sys.executable" 


"ugs occi bd ton 





virtualenv 环境 的 数量 没有 上 限 。 这 里 我 们 再 来 搭建 一 个 名 为 another-venv 的 virtualenv 环境 
( LIST 3.6 )。 


EJLIST3.6 搭建 另 一 个 virtualenv 环境 
S virtualenv another-venv 
S ls -F 


another-venv/ venv/ 





使 用 another-venv 环境 的 Python 时 ， 我 们 无 法 import 其 他 virtualenv 环境 安装 的 库 。 


© LIST 3.7 ”运行 另 一 个 virtualenv 环境 的 Python 


$ source another-venv/bin/activate 
(another-venv)$ python 
BYENGN 2.7,.6 etate Mer 22 2014, 22:59:56) [CCC 4.8.2] mast me 
Type "help", "copyright", "credits" or "license" for more information. 
>>> import sys 
>>> SyS.executable 
' /home/bpbook/work/another-venv/bin/python!' 
>>> import requests 
Traceback (most recent call last): 
Wille "wcstdqgnme" Line l, ln «modules 


ImportError: No module named 'requests' 





可 见 ， 每 一 个 virtualenv 环境 都 是 相互 独立 运行 的 Python 环境 (LIST 3.7 )。 而 且 每 个 环 
境 都 仅 由 Python 的 一 部 分 文件 构成 ， 所 以 能 够 很 快 搭建 完成 或 者 删 摊 ， 并 不 会 占用 太 多 硬盘 


空间 。 
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EX2) virtualenv 环境 的 硬盘 使 用 量 
在 Ubuntu 14.04 F, Python 主体 的 硬盘 使 用 量 大 约 为 100 MB， 每 个 virtualenv 环境 的 硬 
盘 使 用 量 约 为 6 MB。 不 过 ， 如 果 使 用 了 我 们 后 面 即 将 了 解 的 --always-copy 选项 ， 那 么 每 个 
virtualenv 环境 将 占用 约 50 MB。 





不 再 使 用 的 virtualenv 环境 可 以 连同 其 所 在 目录 一 起 删除 ( LIST 3.8 )。 


© LIST 3.8 删除 virtualenv 环境 


(another-venv)$ deactivate 


S rm -R another-venv 


在 不 activate 的 状态 下 执行 virtualenv 环境 的 命令 

我 们 执行 activate 命令 启动 virtualenv 环境 时 ， 环 境 变 量 会 被 更 新 ， 此 后 执行 命令 时 会 
优先 使 用 venv/bin/ 目录 下 的 文件 。 实 际 上 ， 即 便 是 在 没有 执行 activate 命令 的 状态 下 ， 只 要 
我 们 用 完整 路 径 执行 了 venv/bin/ 下 的 命令 ， 束 可 以 运行 virtualenv 环境 中 的 程序 。 


$ python -c "import sys; print sys.executable" 


/usr/local/bin/python 


$ venv/bin/python -c "import sys; print sys.executable" 


/ home /bpbook /work/venv/bin/python 

$ venv/bin/python 

s>> import requests # 可 以 从 venv 环 境 中 导入 
$ venv/bin/pip install flask # 安装 到 venv 环 境 中 


因此 ， 当 我 们 想 有 计划 地 执行 venv 环境 的 程序 ， 或 者 想 局 动 服务 器 时 ， 只 要 用 完整 路 径 指 
定 venv 环境 的 程序 ， 就 可 以 在 不 执行 activate 命令 的 状态 下 完成 运行 了 。 


€ virtualenv 的 选项 
virtualenv 为 用 户 提 供 了 许多 可 用 选项 。 我 们 可 以 通过 virtualenv --help 来 查看 选项 列 
表 。 现 在 我 们 选 其 中 一 些 比较 好 用 的 选项 来 了 解 一 下 


e -p, --python 
指定 virtualenv 环 境 下 使 用 的 Python， 格 式 如 - -pychon-/usr/1local/bin/python2.7. 
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如 采 省 略 该 选项 ， 则 默认 选择 执行 virtualenv 命 令 的 Python。 

e --system-site-packages 
使 用 当前 Python 主体 上 已 经 安装 的 程序 库 。 如 果 省 略 该 选项 ， 则 默认 忽略 Python 主体 上 
已 经 安装 的 程序 库 。 

e --always-copy 
无 论 符号 链接 是 否 可 用 ， 一 概 不 使 用 符号 链接 ， 而 是 和 耳 接 复制 文件 。 即 便 是 允许 使 用 符 
号 链接 的 OS， 在 某 些 文件 系统 下 仍 会 出 现 符 号 链接 不 可 用 的 情况 。 此 时 就 可 以 用 到 这 个 




















选项 。 
e --clear 

MUR TR XE B virtualenvP rp EBORE AE, IGNES e 
e -q, -quiet 


执行 virtualenv 命 令 时 ， 控 制品 工作 台 输 出 的 信息 量 。 
e -y. -verbose 


执行 virtualenv 命 令 时 ， 增 加 向 工作 台 输 出 的 信息 量 。 








E LIST 3.9 virtualenv 的 选项 示例 


$ virtualenv -q --system-site-packages -p /usr/local/bin/python2.7 venv 


如 果 我 们 经 常用 到 某 些 选 项 ， 可 以 事先 将 其 写 和 人 设置 文件 。 这 样 一 来 ,我 们 就 不 用 每 次 执 
行 命令 时 都 再 写 一 和 了 。 

fr Linux 系统 下 ， 设 置 文件 默认 使 用 $HOME/.virtualenv/virtualenv.ini。 举 个 例子 ， 如 果 要 
在 virtualenv.ini 中 指定 LIST 3.9 里 的 选项 ， 我 们 可 以 按照 LIST 3.10 进行 描述 。 











& LIST 3.10 virtualenv.ini 


[virtualenv] 
pyhone /Uae doeddqe bum Es ora 
quiet - true 


system-site-packages = true 


男 外 ， 还 可 以 在 环境 变量 中 指定 选项 。 如 果 我 们 同时 用 环境 变量 和 设置 文件 指定 了 某 个 选 
项 ， 那 么 将 以 环境 变量 的 指定 为 准 。 当 然 ， 命 令 行 传 值 参数 的 指定 优先 于 一 切 。 

环境 变量 名 是 根据 选项 名 自动 生成 的 。 将 选项 名 的 “- -” 后 的 字母 全 改 为 大 写 ， 短 线 改 为 
下 划 线 ， 然 后 在 开头 加 上 VIRTUALENV_， 就 是 该 选项 所 对 应 的 环境 变量 。 请 各 位 在 设置 环境 
变量 时 记 住 这 个 规律 。 














邮 
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e 示例 
--quiet -> WIRTUABENV QUIET=true 
- -python -> VIRTUALENV PYTHON-/usr/local/bin/python2.7 


--System-site-packages -> VIRTUALENV SYSTEM SITE PACKAGES-true 


EZ-) --system-site-packages 选项 

virtualenv 环境 不 会 引用 Python 主体 上 安装 的 程序 包 ， 也 就 是 /usr/local/lib/python2.7/site- 
packages 目录 下 的 程序 包 。 因 此 ， 当 我 们 新 建 了 一 个 virtualenv 环境 时 ， 这 个 环境 处 于 干净 的 
切 始 状态 ， 疫 有 安装 任何 多 余 的 包 。 

相反 地 ， 如 果 我 们 想 在 virtualenv 环境 中 使 用 Python 主体 上 安装 的 程序 包 ， 那 么 在 新 建 环 
HJ Se ee we 

aee EEE 我 相当 于 同时 全 用 两 ， 因 此 很 难 分 辨 出 程序 包 在 哪 
里 ， 以 及 正在 使 用 的 是 哪个 程序 包 。 这 会 导致 virtualenv 环境 的 优势 大 打折 扣 。 所 以 ， 除 非 迫 不 
PE Ru puce NN MM QS 


3.2.2 用 pip 安装 程序 包 


NOTE 
我 们 使 用 的 是 pip 1.5.6。 


给 virtualenv 环境 额外 安装 程序 包 时 ， 需 要 用 该 环境 的 pip fu. 
pip 是 用 来 安 疙 程序 包 的 命令 。 既 可 以 经 由 网 络 进行 安装 ， 也 可 以 直接 从 本 地 的 程序 包 文 件 





进行 安装 。 第 三 方 的 程序 库 发 布 在 PyPI E. pip 命令 会 默认 从 PyPI 上 搜索 并 安装 程序 包 。 





pip 提供 了 多 个 子 命令 。 下 面 便 是 其 子 命令 列表 。 


install 安装 程序 包 ( 指定 包 名 、 包 文件 名 、URL 等 ) 





uninstall 撮 载 程序 包 





freeze 以 requirements 格式 列表 输出 当前 已 安装 的 程序 包 及 其 版 本 





list 列表 显示 当前 已 安装 的 程序 包 





show 列表 显示 当前 已 安装 程序 包 的 版 本 信息 
search 按 指定 关键 字 在 PyPl 上 搜索 程序 包 并 显示 结果 列表 





wheel 根据 指定 requirement 构建 wheel 文件 
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接 下 来 ,我们 将 对 pip 的 选项 以 及 安 又 、 番 载 方 法 进行 学 习 。 其 他 详细 内 容 请 参考 以 下 
网 站 。 


Reference Guide - pip 1.5.6 documentation 
https://pip.pypa.io/en/latest/reference/index.html 

User Guide - pip 1.5.6 documentation 
https://pip.pypa.io/en/latest/user guide.html#configuration 








@ pip 的 选项 

pip 的 选项 有 两 种 ， 一 种 是 不 依赖 于 子 命令 的 共通 选项 ， 另 一 种 是 指定 给 子 命 令 的 选项 。 比 
如 --quiet 和 --proxy 就 是 所 有 命令 共通 的 选项 ， 而 install 子 命令 则 拥有 --upgrade 等 自己 独 有 的 
选项 ( LIST 3.11 )。 

这 两 种 选项 都 需要 在 执行 时 通过 命令 行 指 定 。 











© LIST 3.11 pip 的 选项 示例 


$ pip --quiet --proxy-server:9999 install --upgrade requests 





常用 的 选项 可 以 事先 写 在 设置 文件 中 。 这 样 可 以 省 去 每 次 部 写 的 抹 烦 。 
Linux 的 默认 设置 文件 为 SHOME/pip/pip.conf。 比 如 我 们 要 在 pip.conf 中 指定 LIST 3.11 pip 
的 选项 示例 中 的 选项 ， 则 可 以 按照 LIST 3.12 进行 描述 。 


© LIST 3.12 pip.conf 


[global] 
quiet = true 


Dry = ervers; 9999 


Linstall] 


upgrade = true 


NOTE 
上 述 内 容 只 是 个 例子 ， 并 非 推荐 设置 。 各 位 请 严格 按照 目 己 的 需要 设置 各 个 选项 。 





男 外 ， 还 可 以 在 环境 变量 中 指定 选项 。 如 琳 我 们 同时 用 环境 变量 和 设置 文件 指定 了 某 个 选 
M, 那么 将 以 环境 变量 的 指定 为 准 。 当 然 , 命令 行 传 值 参 数 的 指定 优先 于 一 切 。 

环境 变量 名 是 根据 选项 名 目 动 生成 的 。 将 选项 名 的 “--” 后 的 字母 全 改 为 大 写 ， 短 线 改 为 
下 划 线 ， 然 后 在 开头 加 上 PIP_， 就 是 该 选项 所 对 应 的 环境 变量 。 请 各 位 在 设置 环境 变量 时 记 住 
这 个 规律 。 
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e 示例 
--quiet S GEDBESOUEEN IG 
EU z DIPPODROXY-Server0s9999 


= 一 DOESGE => PIP UPGRADE=LTUE 


关于 指定 HTTP 代理 


pip 需要 使 用 HTTP 协议 从 外 部 网 站 获取 程序 包 。 在 某 些 企业 或 环境 下 ， 我 们 需要 经 由 代理 
才能 访问 到 外 部 网 站 。 而 且 有 些 时 候 ， 我 们 必须 输入 1D 和 密码 才 可 以 使 用 代理 访问 外 部 网 站 


(认证 代理 )。 


在 这 类 环境 下 使 用 pip 时， 我 们 要 用 --proxy 选项 指定 人 代理， 格式 为 [user:passwae] 


pros Server Core(aST er on 


© LIST 3.13 指定 pip 的 代理 


$ pip --proxy=proxy.example.com:1234 install requests 


© LIST 3.14 指定 pip 的 认证 代理 


$ pip --proxy=beproud:passwd@proxy.example.com:1234 install requests 


我 们 也 可 以 像 LIST 3.15 这 样 ， 在 设置 文件 或 环境 变量 中 指定 --proxy 选项 。 


回 LIST 3.15 在 PIP_PROXY 环境 变量 中 指定 


$ export PIP PROXY-proxy.example.com:1234 
$ pip install requests 


除 PIP_PROXY 环境 变量 外 ， 我 们 还 可 以 在 HTTP_PROXY 环境 变量 中 指定 Proxy 


ISO 


E LIST 3.16 TEHTTP. PROXY 环境 变量 中 指定 


$ export HTTP PROXY-proxy.example.com:1234 
$ pip install requests 


e 安 效 程序 包 


o4 


pip install 是 安装 程序 包 的 命令 。install 子 命令 可 以 详细 指定 “安装 什么 ”“ 从 哪里 安 


装 ”“ 如 何 安 闻 "。 因 此 ， 我 们 在 看 帮助 文档 时 会 发 现 尼 有 很 多 选项 和 对 象 指定 方法 (LIST3.17 )。 


© LIST 3.17 pip install 的 帮助 


Seo ase 人 


Usage: 
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pip install [options] «requirement specifier» ... 


pip install [options] -r «requirements file» ... 
pio install [options] l-el] eves project urls sos 
parpsemsqatleeptbaonsleelelocaltoproyectopati- ,6 


plp install lopticons] er ebavesusd st 


从 PyPI 安装 程序 包 的 方法 如 LIST 3.18 所 示 。 这 里 ， 我 们 可 以 指定 一 个 或 多 个 程序 包 。 


回 LIST 3.18 从 PyPI 安装 


$ pip install requests 
$ pip install flask bottle 





如 条 手边 有 源码 ， 还 可 以 像 LIST 3.19 这 样 进 行 安 装 。 


加 LIST 3.19 ”从 源码 包 安 装 


$ pip install ./logfilter-0.9.2 





f E. fn] oc FEM Ad B RKR, Rims HR, WM ./logfilter-0.9.2 或 
file://logfilter-0.9.2 246, WIR H5 pip install logfilter-0.9.2, 计算 机 会 跑 
到 PyPI 上 去 找 名 为 1ogfilter-0.9.2 的 程序 包 。 

从 源码 安装 时 ， 我 们 可 以 使 用 -e ( --editable ) 选项 。 这 样 一 来 ， 安 闭 时 不 会 复制 源码 ， 而 是 
和 耳 接 在 该 目录 下 原 地 进行 安装 。 对 于 一 些 尚 在 开发 中 的 源码 ， 用 editable 进行 安 疙 可 以 省 去 每 次 
修改 代码 后 重新 安 半 的 麻烦 (LIST 3.20 )。 由 于 程序 可 以 在 运行 时 和 下 接 使 用 我 们 编辑 过 的 代码 ， 
所 以 editable 也 被 称 为 可 编辑 安 疙 。 




















E LIST 3.20 指定 editable 安装 源码 目录 


$ pip install -e ./logfilter-0.9.2 





将 版 本 库 clone 下 来 并 进行 安 妆 时， 需要 在 版 本 库 的 URL 前 添加 例如 hg+ 等 版 本 库 类 别 ， 
然后 再 执行 pip install (LIST 3.21). 在 执行 本 例 的 过 程 中 ， 需 要 在 内 部 使 用 hg 命令 ， 因 此 
必须 有 一 个 可 以 使 用 hg 命令 的 环境 。 对 象 为 git 版 本 库 时 请 将 上 述 hg FN gito 

现在 让 我 们 来 执行 安 半 。 











Ej LIST 3.21 从 hg 上 clone 并 安装 


$ pip install hg-«https://bitbucket.org/shimizukawa/logfilter 





如 果 想 在 clone 来 的 源码 上 进行 开发 ， 我 们 可 以 同时 加 上 -e 选项 。 此 时 需要 如 LIST 3.22 所 
IR, Æ URL KÆ #egg=<< 程序 包 名 >>。 
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© LIST 3.22 JA hg 上 clone 并 editable 安装 
$ pip install -e hg-«https://bitbucket.org/shimizukawa/logfiltertstegg-logfilter 
FEFE, EESTI EI 73 3L ROG] A EE FA A R ARA EFEN ELA 


XE 
CEAN 


如 条 要 一 次 安 
requirements 格式 的 文件 。 文 件 名 一 般 使 用 requirements.txt。 我 们 可 以 自己 动手 准备 这 个 文件 ， 
不 过 一 般 我 们 都 会 用 pip freeze 来 输出 。requirements.txt 文件 用 -r ( --requirement ) 选项 指定 


( LIST 3.23 )。 
通过 requirements.txt 安装 
使 用 pip 时， 如 采 之 前 已 经 安装 过 指定 的 程序 包 ， 计 算 机 并 不 会 目 动 将 其 更 新 为 新 版 本 。 


© LIST 3.23 
$ pip install -r requirements.txt 





指定 更 新 到 革 一 版 本 需要 用 -U ( --upgrade ) 选项 ( LIST 3.24 )。 


Ej LIST 3.24 用 -U 选项 更 新 版 本 
$ pip install -U requests 

如 果 不 想 每 次 都 从 PyPI 下 载 程序 包 ， 我 们 可 以 用 --download-cache 选项 指定 绥 存 目录 
(LIST 3.25 )。 此 时 ， 为 了 检查 版 本 ， 计 算 机 仍 会 进行 网 络 通 信 。 如 末 绥 存 目录 中 有 我 们 要 用 的 


版 本 ,计算 机 则 会 下 接 用 绥 存 文件 进行 安 半 。 


Ej LIST 3.25 ”指定 下 载 缓存 
$ pip install --download-cache--/.pip-cache requests 
XL 


如 果 想 一 直 使 用 绥 存 目录 ， 建 议 各 位 在 环境 变量 中 设置 该 选项 ( LIST 3.26 )。 只 要 维持 环境 








变量 中 的 这 一 设置 ， 我 们 就 能 有 效 运 用 绥 存 。 
Ej LIST 3.26 在 环境 变量 中 设置 下 载 缓存 
$ export PIP DOWNLOAD CACHE--/.pip-cache 


$ pip install requests 


从 pip-6.0 起 ， 下 载 缓存 改 为 默认 有 效 。 指 定 --download-cache 选项 时 会 出 现 无 效 警 告 。 





NOTE 
e 记录 程序 包 一 览 表 
pip freeze 命令 用 来 将 已 安装 程序 包 及 其 版 本 的 一 览 表 以 requirements 格式 输出 。 其 执行 


tl LIST 3.27 所 示 。 
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© LIST 3.27 pip freeze 


$ pip freeze 
Elask 0 10.1 
Jinga2==2. 7.93 
MarkupSafe==0.23 
Werkzeug==0.9.6 
afgparse--ti.2.1 
itsdangerous--0.24 


wsqguirer--o0. 1.2 


NOTE 
M pip-6.0 起 ， 不 再 显示 Python 标准 库 argparse 4l wsgiref, 


pip freeze LJ requirements 格式 输出 程序 包 及 其 版 本 的 列表 。 为 了 方便 pip install 使 
用 这 些 内 容 ， 它 们 会 被 保存 在 requirements.txt 文件 中 (LIST 3.28 )。 这 个 文件 名 并 不 是 人 硬性 要 
求 ， 但 大 多 数 情况 下 我 们 习惯 使 用 requirements.txt。 








回 LIST 3.28 将 pip freeze 的 输出 保存 在 requirements.txt 中 


$ pip freeze > requirements.txt 


这 样 一 来 ， 我 们 就 可 以 用 类 似 pip install -r requirements.txt 的 方式 在 其 他 环境 
中 安装 相同 版 本 的 程序 包 了 。 

如 果 环 境 中 安装 的 程序 包 发 生变 动 ， 我 们 可 以 再 次 执行 pip freeze > requirements.txt, 
以 更 新 文件 内 容 。 此 时 ， 用 -r C--requirement ) 选项 指定 原来 的 requirements.txt 可 以 确认 更 新 前 
后 的 差别 ( LIST 3.29 )。 用 这 种 方法 能 帮助 我 们 确认 是 否 存 在 意外 更 改 。 

















© LIST 3.29 pip freeze -r 的 结果 


$ pip install bottle 

$ pip freeze -r requirements.txt 

Plask==0,.10,1 

omga? = > 

MarkupSafe==0 .23 

Werkzeug==0.9.6 

argparse--1.2.1 

itsdangerous--0.24 

wsgiref==0.1.2 

44 The following requirements were added by pip --freeze: 


Ines 
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f£ requirements.txt 内 指定 版 本 库 
如 果 我 们 在 当前 环境 下 用 -e( --editable ) 安装 了 版 本 库 的 代码 ， 那 么 执行 pip freeze m, 
输出 结果 如 下 。 
$ pip install -e hg+https://bitbucket.org/shimizukawa/logfilter#egg=logfilter 
$ pip freeze 
-e hg«https://bitbucket.org/shimizukawa/logfiltere96fd26dae42053c015d3285c 
002d45aa5fe6e324tdegg-logfilter-dev 
Flask==0.10.1 
Jinja2==2.7:3 
MarkupSafe==0.23 
Werkzeug==0.9.6 
itsdangerous==0.24 
wsgiref==0.1.2 
该 版 本 库 特定 版 本 的 代码 会 被 安装 到 使 用 requirements.txt 进行 pip install 时 的 环境 
中 。 所 以 各 位 请 注意 ， 安 装 时 会 执行 版 本 库 clone 操作 ， 而 且 无 论 版 本 库 是 否 接 到 了 新 的 提交 ， 


安装 时 都 会 使 用 我 们 指定 的 版 本 。 


e ERIE E 
pip uninstall dH THE. MEAE KRETE. HAITI IRU LIST 3.30 所 示 。 


© LIST 3.30 pip uninstall 


$ pip uninstall flask 
Uninstalling flask: 
/home/bpbook/work/venv/lib/python2.7/site-packages/... 


Proceed (y/n)? y 


Successfully uninstalled flask 


屏幕 上 会 显示 竺 删除 文件 的 列表 ， 并 辐 用 户 询问 是 否 真 的 要 删除 。 此 时 输入 y 并 按 下 Enter 
键 即 可 完成 删除 操作 。 
如 果 不 需 要 确认 ， 可 以 加 上 -y( --yes ) 选项 ， 其 执行 如 LIST 3.31 所 示 。 








© LIST 3.31 pip uninstall -y 


$ pip uninstall -y flask 


请 注意 ，pip uninstall fp RAZHARIIK EIET. KUKI Flask 时 会 捆绑 安装 
Jinja2 等 4 个 关联 程序 包 ， 这 些 程序 包 在 Flask 被 印 载 之 后 仍 会 残留 在 环境 中 。 如 果 我 们 不 再 需 
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要 这 些 程序 包 ， 就 必须 通过 pip uninstall 手动 删除 它们 ， 或 者 直接 重建 virtualenv 环境 ， 选 
我 们 需要 的 程序 包 重 新 安装 。 


3.2.3 小 结 


FÈ Python HHEH, 我们 可 以 用 virtualenv 搭建 该 项 目 专用 的 虚拟 环境 。 有 了 这 个 环境 ， 
我 们 使 用 程序 库 时 就 不 会 影响 到 其 他 项 目 了 。 项 目 所 需 的 程序 库 用 pip 进行 安装 。 用 pip 
freeze 命令 搭建 某 项 目 环境 的 requirements.txt 文件 之 后 ， 我 们 能 够 轻松 重建 该 项 目 所 需 的 环 
境 。 除 此 之 外 ， 部 署 等 方面 也 有 pip 和 virtualenv 的 用 武之 地 。 这 两 个 工具 是 Python 开发 环境 的 
基础 ， 建 议 各 位 牢记 它们 的 使 用 方法 。 








3.3 ”文件 结构 与 发 布 程序 包 





编写 完 程 序 之 后 ， 我 们 还 要 面 对 从 封装 成 包 到 发 布 的 复杂 流程 。 在 本 部 分 中 ， 我 们 会 答 试 
把 第 2 章 中 开发 的 留言 板 应 用 放 到 PyYPI 上 进行 公开 ， 并 在 此 过 程 中 学 习 一 下 setup.py 的 与 法 以 
及 如 何 问 PyPI 上 传 程序 包 等 。 








3.9.1 编写 setup.py 


首先 我 们 来 了 解 一 下 setup.py 的 功能 。Python 的 封装 离 不 开 setup.py。 将 开发 完毕 的 程序 封装 
成 包 ， 可 以 方便 其 他 用 户 或 其 他 项 日 拿 去 用 。 而 封装 的 绝 大 部 分 时 间 都 要 消耗 在 编写 setup.py 上 。 

我 们 用 setup.py 来 设置 Python 程序 包 的 信息 (元 数据 )、 定 义 程 序 包 。setup.py 这 个 文件 名 
是 Python 中 定好 了 的 ,不 可 以 更 改 。 我 们 要 在 这 个 文件 中 定义 程序 包 名 称 、 包 及 依赖 包 的 信息 
等 元 数据 。 

有 了 setup.py 之 后 ， 我 们 便 能 在 命令 行 中 执行 诸如 python setup.py sdist fll python 
setup.py install 等 与 包 相 关 的 操作 了 。 男 外 ， 将 程序 包 注 册 到 PyPI 的 操作 也 需要 通过 
setup.py 进行 。 

















@ setup.py 的 命令 
首先 ， 我 们 来 做 出 一 个 能 运行 的 setup.py 2356 ( LIST 3.32 )。 


© LIST 3.32 setup.py 


from setuptools import setup 


setup (name='guestbook') 
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现在 计算 机 已 经 可 以 执行 setup.py 的 命令 了 。 各 位 可 以 通过 --help-commands 选项 查看 
setup.py 提供 的 命令 (LIST 3.33 )。 我 们 在 下 面 列 举 了 一 些 有 代表 性 的 命令 。 命 令 后 面 的 英文 注 
释 已 经 详 为 了 中 文 。 





& LIST 3.33 setup.py 的 指令 一 览 


$ python setup.py --help-commands 


bciist wininst 


upload docs 


标准 命令 
build 构建 安装 所 需 的 全 部 内 容 
clean 删除 'build' 命令 创建 的 所 有 临时 文件 
install 安装 build 目录 下 的 全 部 内 容 
sdist 创建 源码 包 (M tar, zip 等 格式 ) 
register 将 程序 包 注 册 到 Python Package Index 
Ba 创建 二 进 制 包 
bdist dumb $E ' dumb' 格式 的 二 进 制 包 
bdist rpm 创建 RPM 格式 的 二 进 制 包 


创建 面向 MS Windows 的 安装 包 


upload 将 二 进 制 包 上 传 至 PyPI 
check 检查 程序 包 的 设置 值 是 否 正 确 
扩展 命令 
develop 以 开发 模式 安装 程序 包 
setopt 在 setup .cfg 等 文件 中 记录 一 1 
saveopts 将 给 定 的 多 个 选项 记录 在 setup.cfg T 


m PyPI ENE 


alias 定义 快捷 命令 
bdist egg 创建 'egg' 格式 的 程序 包 
EXE 原 地 构建 后 运行 Unit Test 








下 面 我 们 来 创建 最 基本 的 源码 包 。 


源码 包 需 要 通过 python setyp.py sdist 命令 创建 


(LIST3.34 )。 


© LIST 3.34 python setup.py 


$ python setup.py sdist 
running sdist 
running egg inre 
- ( 中间 省 略 ) - 
sdist: standard file mot found: 


warning: should have one of README, README.rst, d 


README . txt 


running check 


warning: check: missing required meta-data: url 
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wanmumae Check: missing meta-Cace: either (auchor end author email) Ee d pb d 


ner and maintainer email) must be supplied 


creating guestbook-0.0.0 
- ( 中 间 和 省 略 ) - 

creating dist 

Creating tar archive 


removing 'guestbook-0.0.0' (and everything under it) 


$ le dist/ 
questibook- 0-050. ee 





MÆ, dist 目录 下 已 经 生成 了 guestbook-0.0.0.targz 文件 。 这 个 tar.gz 文件 目前 只 包含 setup.py。 
另外 ， 我 们 在 执行 过 程 中 看 到 了 几 个 warning。 这 些 warning 指出 的 项 目 最 好 都 设置 一 下 。 
后 面 我 们 会 学 习 如 何 进 行 设置 。 


3.3.2 ”留言 板 的 项 目 结构 


首先 ， 我 们 来 了 解 一 下 Python 项 目 一 般 的 目录 结构 。 当 封装 对 象 只 有 一 个 “.py” 文 件 时 ， 
其 结构 如 LIST 3.35 所 示 。 


加 LIST 3.35 项 目 内 只 有 一 个 文件 时 的 结构 示例 


/ home /bpbook/projectname 
+-- MANIFEST.in 
+-- README.rst 
+-- packagename.py 


duc IS 





ADABPROMAR Hox PaL “py” KERRE, MAAN LIST 3.36 所 示 。 


加 LIST 3.36 项目 内 含 多 个 文件 时 的 结构 示例 
/home/bpbook/projectname 
+-- MANIFEST.in 
r-- README .rst 
+-- packagename/ 
| +-- | init  .py 
| --- module.py 
| +-- templates/ 
| +-- index.html 


e Setup 





关于 这 方面 ， 我 们 的 留言 板 应 用 由 下 述 文件 组 成 。 
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服务 器 程序 


提交 数据 文件 





CSS 文件 
输出 HTML 的 模板 ， 用 于 显示 “提交 /留言 列表 ”的 页 面 








虽然 “.py” 文 件 只 有 一 个 ,但 static FH templates 目录 下 都 包含 文件 。 由 于 我 们 介绍 的 前 一 
种 项 目 结构 无 法 安装 模板 等 文件 ， 因 此 这 里 需要 使 用 后 一 种 项 目 结构 。 
文件 最 终 的 安排 如 LIST 3.37 所 示 。 





© LIST 3.37 留言 板 项 目的 目录 结构 
/ home /bpbook /guestbook/ 
CS SOIN RUINIS BSEC 
+-- MANIFEST.in 
+-- README.rst 
+-- guestbook 
| +-- | init  .py 
| == Gtiatic/main.css 
| +-- templates/index.html 
+== SETUD .OY 


现在 我 们 来 创建 guestbook HÆ, Tf guestbook.py 文件 移动 到 该 日 录 下 并 重合 名 为 “__ 
init .py" (init 前 后 各 两 个 半角 下 划 线 )。 男 外 ，templates 和 static 目录 也 要 移动 到 guestbook H 
录 下 。guestbook.dat 不 是 我 们 要 发 布 的 东西 ， 所 以 这 里 不 需要 它 。 

接 下 来 ， 我 们 来 实际 应 用 这 个 封装 用 的 结构 。 





3.3.3 setup.py 与 MANIFEST.in 一 一 设置 程序 包 信 息 与 捆绑 的 文件 


接 下 来 我 们 将 在 setup.py 中 设置 程序 包 的 信息 ， 然 后 在 MANIFEST.in 中 指定 捆绑 的 文件 。 
那么 ， 我 们 先 来 按照 顺序 了 解 一 下 。 


@ Setup.py 
Hc. RHR LIST 3.38 这 样 描述 guestbook 项 目的 setup.py。 


© LIST 3.38 ”最低 限度 内 容 的 setup.py 


from setuptools import setup, find packages 


setup ( 


name-'guestbook'!, 
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VEESlCns' 1L.0-0'， 

packages-find packages(), 

include package data=True, 

install requires-[ 
"Plask' , 

IE 


如 果 一 个 环境 能 使 用 pip， 那 么 该 环境 中 一 定安 装 了 setuptools 库 。 虽 然 用 from distutils.core 
import setup 这 种 Python 标准 写法 也 没有 问题 ， 但 一 般 情 况 下 我 们 习惯 使 用 setuptools 提供 的 含 
有 扩展 功能 的 setup PAZ 

下 面 来 了 解 一 下 各 个 参数 的 音义 。 





* name 
程序 包 的 名 称 。 这 里 我 们 定 为 'guestbook'。 一 般 情 况 下 ， 包 名 都 与 项 目 名称 一 致 。 但 是 ， 
用 于 发 布 的 程序 包 需 要 有 一 个 独特 的 名 称 ， 以 防止 与 其 他 程序 包 名 撞车 。 实 际 上 ， 
guestbook 这 个 名 称 实在 不 驶 独特。 因此， 如果 一 定 要 使 用 这 个 名 称 ， 最 好 在 前 面 加 上 组 
织 名 等 ， 例 如 beproud.guestbook。 

* version 
代表 版 本 号 的 字符 串 。 这 里 我 们 定 为 '1.0.0'。 

e packages 
指定 所 有 捆绑 的 Python 程序 包 (可 以 用 python 命 令 imnport 的 目录 名 ) 。 举 个 例子 ， 如 果 
一 个 项 目 包 含 多 级 目录 ， 那 么 我 们 震 要 用 下 例 所 示 的 方法 ， 列 表 指 定 所 有 程序 包 。 




















packages-[ 
'guestbook', 'guestbook.server!', 'guestbook.server.dir', 
'guestbook.storage', ... 


l, 


find packages()FAZ HT LJ E 3118 2& A Hoe P BJ Python &3f3& El f2 T (45 A Y 
它 ， 我 们 便 可 以 省 去 一 个 个 列举 的 有 抹 烦 。 





NOTE 


如 果 项 目 仅 由 一 个 “.py” 文 件 构 成 ， 那 么 要 用 py. modules 代替 packages 传 值 参数 ， 在 
py. modules 中 指定 对 象 模块 名 。 


e include package data 
在 packages 指 定 的 Python 包 C 目录 ) 中 ， 除 “.py” 之 外 的 文件 都 称 为 程序 包 资 源 。 这 个 
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设置 用 来 指定 是 否 安装 Python 包 中 所 含 的 程序 包 资 源 。 
这 里 我 们 要 安装 templates 和 static 这 两 个 程序 包 资 源 ， 所 以 将 它们 指定 为 True。 
不 过 ， 这 一 设置 并 不 能 将 程序 包 换 源 与 我 们 要 发 布 的 程序 包 捆 绑 在 一 起 。 捆 绑 的 方法 将 
在 MANIFESTin 中 学 习 。 

e install requires 
列表 指定 依赖 包 。 留 言 板 应 用 要 依赖 Flask， 所 以 我 们 在 这 里 指定 Flask。 与 requirements. 
txt 人 不同 ， 这 里 一 般 不 指定 版 本 。 


€ MANIFEST.in 

为 将 HTML 文件 、CSS 文件 等 程序 包 资 源 与 程序 包 拥 绑 在 一 起 ， 我 们 需要 用 MANIFEST.in 
来 指定 封装 对 象 文 件 。 

这 里 我 们 在 setup.py 所 在 的 目录 下 创建 MANIFEST.in 文件 ， 指 定 封 装 对 象 文件 的 范围 
( LIST 3.39 )。 











© LIST 3.39 MANIFEST.in 


recursive-include guestbook *.html *.css 


recursive-include 表示 捆绑 指定 目录 下 所 有 与 指定 类 型 一 致 的 文件 。 以 LIST 3.39 2g ff], R 
们 捆绑 了 guestbook 目录 下 所 有 与 “*.html” 和 “*.cssS” 一 致 的 文件 。 

现在 我 们 希望 使 用 这 个 程序 包 的 环境 能 安装 这 些 捆绑 好 的 程序 包 资 源 。 为 此 ， 我 们 需要 将 
前 面 提 到 的 install package data 指定 为 True， 这 一 点 干 万 不 能 访 。 

MANIFEST.in 还 可 以 指定 捆绑 guestbook 应 用 不 使 用 的 非 程 序 包 资 源 文 件 ， 比 如 LICENSE. 
txt。 在 发 布 程序 包 时 最 好 把 许可 文件 也 捆绑 进去 。 

假设 我 们 使 用 了 BSD 许可 ， 并 在 LICENSE.txt 文件 中 描述 了 许可 条 款 。 接 下 来 ， 我 们 需要 
在 MANIFEST.in 里 涂 加 对 它 的 拥 绑 指定 (LIST 3.40 )。 


© LIST 3.40 MANIFEST.in 


recursive-include guestbook *.html *.css 


include LICENSE.txt 





include SWARNA -SPEKE — AAF. HARI T LIST 3.40 中 所 示 的 指定 语句 后 ， 
LICENSE.txt 文件 就 和 程序 包 捆 绑 在 了 一 起 。 另 外 ， 我 们 要 安装 的 是 guestbook Ho, m 
LICENSE.txt 文件 并 不 在 该 目录 下 ， 所 以 LICENSE.txt 文件 并 不 会 被 安装 到 使 用 该 程序 包 的 环 
境 中 。 

MANIFEST.in 有 许多 种 描述 方式 ， 不 但 可 以 将 某 个 扩展 名 的 文件 全 部 捆绑 起 来 ， 还 可 以 别 
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除 特 定 扩 展 名 的 全 部 文件 。MANIFESTin 的 详细 描述 方法 请 查阅 Python 的 参考 手册 。 





Creating a Source Distribution - Python 2.7.12 documentation 
https://does.python.org/2.7/distutils/sourcedist.html 





e 确认 运行 
为 查看 前 面 的 设置 是 否 正确 ， 我 们 需要 搭建 一 个 用 来 开发 程序 包 的 virtualenv 环境 并 安 


情况 














JE 





程序 包 。 这 里 我 们 用 “.venv” 作 为 virtualenv 环境 的 目录 名 (LIST3.41 )。 


回 LIST 3.41 


S GQ so 


搭建 virtualenv 环境 及 安装 


S virtualenv .venv 


此 时 的 目录 结构 如 LIST 3.42 所 示 。 


加 LIST 3.42 目录 结构 


/ home /bpbook/guestbook/ 


+-- .venv/ 


T-- hrcCHENSBE.UXt 


+-- MANIFEST.in 


+-- guestbook 


| +-- | init .py 


| poccstatugc/madsnecss 


| emplates dec html 


== erup. Oy 


然后 我 们 启动 virtualenv 环境 并 执行 安装 





。 在 安装 时 请 加 上 -e ( --editable ) 选项 进行 原 地 安 

















装 ( 在原 目录 下 直接 转 为 安装 状态 ) ( LIST 3.43 )。 这 样 一 来 ， 我 们 在 开发 过 程 中 就 不 用 每 改 一 


次 都 重新 安装 


回 LIST 3.43 ”搭建 virtualenv 环境 及 editable 安装 


$ source 


一 衣 了 。 


.venv/bin/activate 


(.venv)$ pip install -e . 


Obtaining file:///home/bpbook/guestbook 





Running setup.py (path:/home/bpbook/guestbook/setup.py) egg info for package d 


from file: 


/ / /home / bpbbook/guestbook 


Installing collected packages: guestbook 


- ( 中 间 省 略 : 安装 依赖 包 ) - 


Running 


setup.py develop for guestbook 
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Creating /home/bpbook/.venv/lib/python2.7/sgite-packages/guestbook.egg-link d 
(link iE e -) 
Adding guestbook 1.0.0 to easy-install.pth file 


Installed /home/bpbook/guestbook 


- (rfjg eil ) - 
Successfully installed guestbook 


Cleaning up... 


(.venv)$ pip freeze 
Eusko 

rS e. 7.3 
Markupoate--0 0295 
Werkzeug-z-z0.9.6 
guestbook==1.0.0 


itsdangerous==0.24 





现在 ，guestbook-1.0.0 已 经 安装 到 virtualenv 环境 中 了 。 我 们 可 以 看 到 ， 记 录 程 序 包 元 数据 
位 置 的 guestbook.egg-link 文件 被 安装 到 virtualenv 环境 中 了 。easy-install.pth 文件 中 添加 了 
guestbook 的 源码 位 置 。 另 外 ，Flask 及 其 相关 程序 包 也 都 安装 好 了 。 

这 样 一 来 ， 我 们 在 其 他 PC 或 服务 需 上 构建 环境 时 ， 就 不 必 再 去 一 个 个 地 安装 依赖 包 了 。 
如 果 今 后 需要 添加 或 更 改 依赖 库 ， 各 位 只 要 按照 前 面 讲 的 流程 更 新 setup.py， 然 后 再 执行 一 次 
pip install 即 可 。 








3.3.4 ”setup.py 一 一 创建 执行 命令 


我 们 在 第 2 革 开 发 的 留言 板 是 一 个 直接 从 Python 局 动 的 脚本 。 要 想 让 下 载 它 的 人 用 起 来 更 
方便 ， 那 最 好 生成 一 些 用 户 命 HB e o 这 里 我 们 通过 设置 setup.py, EIL 目 动 生成 guestbook 命 ap 今 
( LIST 3.44 )。 














Ej LIST 3.44 让 setup.py 生成 命令 


from setuptools import setup 


setup ( 
name= 'guestbook', 
verssons!d-9cQ 
packages=find packages () ， 
edueleneaekaee nla quus 


install nm 
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'"Elask', 


entry porntg=" 0u 
[console Scripts] 


guestbook = guestbook:main 


"uN 
z 





我 们 在 setup.py 中 添加 了 entry points。 这 样 一 来 ， 在 安装 程序 包 时 就 会 日 动 生成 guestbook 
命令 。 用 户 执行 guestbook 命令 时 将 会 调用 guestbook 模块 的 main FR — 


但 是 guestbook/ init. .py 中 还 没有 main 图 数 ， 所 以 我 们 需要 添加 这 个 因数 ， 具 体 代 码 如 
LIST 3.45 所 示 。 


© LIST 3.45 guestbook/ init .py 


def main(): 


exu c eere ror umo eo OR ESI 


it neme == | maim ': 
# Æ IP HEHE 127.0.0.1 K9 8000 端口 运行 应 用 程序 
appolicacion. run ('1127-0.0.-1",;, 8000, cdebug=True) 


然后 我 们 再 次 执行 安装 命令 ， 看 看 是 否 能 生成 guestbook 命令 。 


即便 是 在 editable 安装 的 状态 下 ， 如 果 想 反映 出 对 元 信息 进行 的 修改 C 比如 添加 命令 、 更 改 
依赖 库 等 )， 也 需要 重新 执行 一 次 安装 命令 ( LIST 3.46 )。 


回 LIST 3.46 ”重新 安装 


(.venv)$ pip install -e ./guestbook 
A ERBEN) - 
Successfully installed guestbook 


Cleaning up... 


(.venv)$ ls .venv/bin/guestbook 


guestbook 


(.venv)$ guestbook 
s Rumning on Mets: //127.0.0.1;8000/ 


* Restarting with reloader 





可 以 看 到 ，guestbook 命令 已 经 成 功 生成 ， 而 且 可 以 正常 运行 了 。 
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3.3.5 python setup.py sdist 一 一 创建 源码 发 布 程序 包 
创建 用 于 发 布 的 程序 包 时 ， 需 要 如 LIST 3.47 PTR, 执行 python setup.py sdist 命令 。 


© LIST 3.47 python setup.py sdist 


$ python setup.py sdist 

running sdist 

Tunning egg nto 

writing requirements to guestbook.egg-info/requires.txt 
writing guestbook.egg-info/PKG-INFO 

writing top-level names to guestbook.egg-info/top level.txt 
writing dependency links to guestbook.egg-info/dependency links.txt 
reading manifest file 'guestbook.egg-info/SOURCES.txt' 
reading manifest template 'MANIFEST.in' 

writing manifest file 'guestbook.egg-info/SOURCES.txt' 
running check 

creating guestbook-1.0.0 

- (中间 省 略 ) - 

making hard links in guestbook-1.0.0... 
kondiitNnkingiMhECENSEN unoolk 299 

- ( 中间 省 略 ) - 

Creating tar archive 


removing 'guestbook-1.0.0' (and everything under it) 


$ 1s dist/ 
guestbook-1.0.0.tar.gz 
这 样 ， 我 们 就 在 dist H 5€ F Æ f guestbook-1.0.0.tar.gz, iX T tar.gz X. £F P E 3$ 
guestbook/ init .py, setup.py, LICENSE.txt, HTML, CSS 等 文件 。 
现在 只 要 将 这 个 文件 放 到 我 们 想 安装 应 用 的 环境 中 ， 就 可 以 运行 pip install guestbook- 
1.0.0.tar.gz， 直 接 从 文件 进行 安装 丁 。 





3.3.6 ”提交 至 版 本 库 


我 们 先 将 前 面 的 内 容 提交 到 版 本 库 。 关 于 hg 命令 的 操作 ， 第 1 革 和 第 6 草 中 有 详细 介绍 
日 前 的 目录 结构 如 LIST 3.48 所 示 。 








© LIST 3.48 留言 板 项 目的 目录 结构 
/ home /bpbook /guestbook/ 
+-- .venv/ 


Toc JECHBHNSOB.dt 
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+-- MANIFEST.in 

+-- guestbook 

| X ETT MEI SI 

| +-- gtatic/main.css 

| +-- templates/index.html 
+-- guestbook.dat 

:-- guestbook.egg-info/ 

+-- setup.py 


开发 Python 项 目 时 ， 我 们 习惯 将 setup.py 放 在 版 本 库 最 初级 目录 ( 根 目 录 ) 下 。 这 样 我 们 
就 能 用 pip ECBE M BUS FEETT ER Y s 

另外 ， 有 些 文件 和 目录 是 不 用 保存 到 版 本 库 中 的 。guestbook.dat 文件 的 作用 是 记录 留言 板 
接收 到 的 数据 ， 这 些 数 据 没 必要 记录 到 版 本 库 里 。 

guestbook.egg-info 目录 的 作用 是 记录 程序 包 的 元 数据 。 元 数据 将 在 执行 pip install -e . 时 
目 动 生成 。 如 果 缺 乏 元 数据 ，editable 安装 可 能 无 法 正常 进行 。 不 过 ， 由 于 它 是 在 安装 时 目 动 生 
成 的 ， 所 以 也 不 用 保存 到 版 本 库 。 

“venv” 也 可 以 重新 生成 ， 因 此 不 必 保 存 到 版 本 库 。 

接 下 来 ， 我 们 需要 将 除 上 述 三 者 以 外 的 文件 提交 给 版 本 库 ( LIST 3.49 )。 






































© LIST 3.49 注册 到 版 本 库 

$ cd -/guestbook 

S hg imit 

$ hg add LICENSE.txt MANIFEST.in guestbook setup.py 

$ hg cei -=m moa erste ie 

5b. WRA HARRA FAIT hg status 命令 ， 刚 才 那 些 不 需要 上 传 的 文件 和 目录 仍 会 

显示 为 非 管 理 对 象 文件 。 我 们 需要 在 “.hgignore” 文 件 中 添加 设置 ， 将 这 些 不 需要 管理 的 文件 
别 除 出 显示 对 象 ( LIST 3.50 )。 








© LIST 3.50 .hgignore 
.*.egg-info 
^guestbook.dat$ 


^ Veny 


“.hgignore” 文 件 也 要 提交 上 去 (LIST 3.51 )。 这 样 一 来 ， 在 其 他 环境 中 使 用 clone 的 版 本 库 
时 也 就 不 会 显示 这 些 文件 了 。 





© LIST 3.51 提交 “.hgignore” 


$ hg add .hgignore 


$ hg el =m Yace. icaore List™ 
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我 们 先 暂 且 将 其 push 到 版 本 库 服务 右上 。 各 位 请 在 Bitbucket 上 创建 一 个 空 的 guestbook 项 
目 ， 然 后 执行 LIST 3.52 所 示 的 命令 。 


© LIST 3.52 hg push 


$ hg push https://bitbucket.org/« ffff)Bitbucket MA »/guestbook 


建议 各 位 今后 适时 地 将 添加 、 修 改过 的 源码 提交 到 版 本 库 中 。 


Ez) Bitbucket 
Bitbucket 是 Mercurial 的 版 本 库 服 务 器 。Bitbucket 为 用 户 提 供 了 许多 免费 功能 ， 可 以 管理 
Mercurial 和 Git 版 本 库 。 
各 位 请 先 注册 账户 ， 创 建 空 的 Mercurial 版 本 库 ， 然 后 执行 LIST 3.53 所 示 的 命令 ， 完 成 
push 操作 ( 本 例 中 的 用 户 名 为 beproud， 版 本 库 名 为 guestbook )。 


Ej LIST 3.53 hg push 示例 


$ hg push https://bitbucket.org/beproud/guestbook 


3.3.7 ”README.rst 一 一 开发 环境 设置 流程 


下 面 我 们 来 描述 设置 流程 说 明 书 ， 总 结 该 留言 板 应 用 开发 环境 的 搭建 流程 。 我 们 前 面 讲 到 
的 流程 如 下 。 


(D clone 项 目的 版 本 库 
D) 搭建 项 目 专用 的 virtualenv 环境 
(3) Y£ virtualenv 环境 内 执行 bip install «directory» (如 果 用 于 开发 ， 则 执行 bip 


install -e «directory» ) 





© LIST 3.54 设置 流程 


hg clone https://bitbucket.org/beproud/guestbook 
cd guestbook 


source .venv/bin/activate 


9 

9 

S virtualenv .venv 

9 

(.venv)$ pip install . 
( 


.venv)$ guestbook 


s Rumning on EDOa/ 和 27.0.0.125000/ 


我 们 来 把 LIST 3.54 中 的 流程 原封 不 动 地 写 人 README.rst。 扩 展 名 为 .rst 的 文件 是 用 
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P7J 
EH 


板 应 用 


r3 


reStructuredText ( reST ) 语法 描述 的 文本 文件 。 一 般 说 来 ，Python 项 目 都 会 选用 reST 语法 来 写 
README.rst, XF reST 语法 ， 我 们 将 在 第 7 章 中 详细 了 解 。 

通常 ，README.rst 包含 LIST 3.55 所 示 内 容 即 可 。 

E LIST 3.55 README.rst 


练习 开发 通过 Web 浏览 器 提交 留言 的 Web 应 用 程序 
工具 版 本 
TERON DIS 
JOPE JE S 
svircualenys 1. 11L.6 
安装 与 启动 方法 
从 版 本 库 获 取代 码 ， 然 后 在 该 目录 下 搭建 virtualenyv 环境 :: 
$ hg clone https://bitbucket.org/beproud/guestbook 
$ cd guestbook 
S virtualenv .venv 
$ source .venv/bin/activate 
(.venv)$ pip install 
(.venv)$ guestbook 


开发 流程 


> Rumaing on htta: //127:0.:0.1:5000/ 


1. 检测 


2. 按 以 下 流程 安装 
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(.venv)$ pip install -e . 


写 完 之 后 要 记得 将 README.rst 文件 提交 到 版 本 库 。 

各 位 请 注意 ， 我 们 在 安装 流程 中 写 的 是 直接 安装 ， 但 在 开发 流程 中 写 的 却 是 用 pip 
install -e 进行 安 闻 。 而 关于 这 二 者 的 区 别 ， 我 们 并 没有 在 README.rst 文件 中 提 及 。 这 是 
因为 我 们 认为 阅读 这 篇 文档 的 人 应 该 懂得 如 何 使 用 pip 的 -e 选项 ， 知 道 有 它 和 没 它 的 不 同 。 使 
用 普及 率 较 高 的 工具 或 选项 的 优势 就 在 于 此 。 即 便 我 们 阅读 文档 时 不 知道 它 是 什么 ， 也 能 立刻 
查 到 相关 资料 ， 或 者 根据 类 似 知识 进行 摸索 。 


























缩短 、 定 型 化 环境 的 搭建 流程 
时 间 一 久 ， 就 算是 自己 开发 的 项 目 ， 我 们 也 会 忘记 如 何 搭建 运行 环境 。 所 以 为 了 将 来 不 亡 
记 ， 我 们 最 好 在 文档 的 开头 就 记 下 运行 程序 之 前 所 需 的 全 部 流程 。 另 外 ， 尽 量 能 让 自己 在 看 文 
档 时 立刻 回想 起 当时 用 了 什么 流程 。 因 此 ， 流 程 要 尽量 短 ， 而 且 要 用 开发 者 们 普遍 采用 的 结构 。 
以 常用 命令 定型 化 的 简洁 流程 具有 以 下 优势 。 


e 不 容易 出 现 键入 错误 、 流 程 颠 倒 等 人 为 失误 

e 减少 整个 项 目 中 需要 记忆 的 东西 

e 需要 向 其 他 开发 者 或 使 用 者 传递 的 信息 更 少 ， 减 少 文档 量 
e 测试 和 部 署 更 容易 目 动 化 


3.89.8 变更 依赖 包 


留言 板 的 依赖 包 是 Flask。 但 是 ， 我 们 很 难 在 开发 初期 束 确 定好 一 于 应 用 程序 内 的 所 有 依赖 
包 ， 有 些 时 候 还 会 放弃 当前 的 包 而 改 用 其 他 的 。 特 别 是 周期 短 、 发 布 频 蚂 的 项 目 ， 往 往 每 发 布 
一 次 都 会 变现 一 次 依赖 包 。 

举 个 例子 ,假设 我 们 放弃 Flask 改 用 Bottle。 这 时 如 有 果 直 接 用 pip 命令 安装 了 Flask 或 
Bottle， 那 就 必须 将 这 一 步 怒 告知 其 他 开发 者 甚至 是 未 来 的 目 己 (LIST 3.56 )。 

















© LIST 3.56 ”用 pip 替换 了 程序 包 ， 这 一 步 该 如 何 告知 其 他 人 


(.venv)s pip uninstall flask 


(.venv)$ pip install bottle 
留言 板 的 setup.py 里 记录 着 依赖 包 的 信息 ， 因 此 我 们 只 需 更 改 setup.py 的 设置 即 可 。 如 果 
改写 了 setup.py 的 install requires 行 ， 需 要 再 次 执行 pip install -e .。 
这 一 步骤 的 命令 和 安装 时 的 命令 一 样 ， 因 此 不 需要 修改 流程 说 明 书 。 只 要 其 他 新 建 项 目 环 
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境 的 开发 者 执行 了 pip install -e . MS, SB d ZR H Bri BJ EHE. 

不 过 ， 还 有 一 点 需要 注意 。 那 就 是 ， 即 使 我 们 从 setup.py 中 删除 了 flask, Bi ZEB 
中 的 Flask 及 其 关联 程序 包 也 不 会 被 印 载 。 要 想 删 除 已 经 无 用 的 程序 包 ， 需 要 用 virtualenv 
--clear . 等 方法 重建 环境 (LIST 3.57 )。 





e LIST 3.57 重建 环境 


(.venv)$ virtualenv --clear .venv # 删除 .venv 环境 内 的 全 部 依赖 库 
(en nel en # 根据 . /setup .py 安装 依赖 库 


这 一 处 理会 重新 安 竣 依赖 库 ， 所 以 运行 时 将 占用 较 长 时 间 。 





NOTE 
建议 各 位 设置 pip 的 --download-cache 选项 ， 缩 短 下 载 时 间 ( pip-6.0 之 前 的 版 本 )。 使 用 


第 9 章 中 介绍 的 wheelhouse 能 进一步 加 快速 度 。 


NOTE 
关于 如 何 固定 开发 环境 中 安 狼 的 程序 包 的 版 本 ， 各 位 请 参考 第 9 草 。 另 外 ， 第 9 草 还 会 讲 
解 强制 指定 依赖 包 汇 围 的 相关 知识 。 


另外 ， 最 好 在 README.rst 中 添加 LIST 3.58 所 示 的 流程 。 


© LIST 3.58 README.rst 
开发 流程 


1. Er ^^setup.py^" 的、 人 ~instal1l requires 
2. 按 以 下 流程 更 新 环境 : : 


(.venv)$ virtualenv --clear .venv 


(.venv)$ pip install -e ./guestbook 


3. 将 setup.py 提交 到 版 本 库 
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3.3.9 通过 requirements.txt 固定 开发 版 本 


前 面 我 们 介绍 了 用 setup.py 管理 依赖 包 的 方法 。 实 际 上 ， 我 们 还 可 以 用 requirements.txt 管 
理 依赖 库 。 

setup.py 是 在 PyPI 上 发 布 程序 包 时 必 不 可 少 的 组 成 部 分 ， 而 且 安 装 时 的 依赖 库 也 需要 
用 setup.py 的 install requires 来 指定 。 这 种 情况 下 ， 由 于 使 用 该 包 的 各 个 环境 大 不 相同 ， 所 
以 我 们 不 能 严格 指定 依赖 库 的 版 本 ， 只 能 指定 最 低 需 求 。 当 然 ， 我 们 还 可 以 手动 编辑 
requirements.txt， 人 免除 指定 版 本 的 工作 。 但 要 知道 ，pip install guestbook 是 不 会 引用 
requirements.txt 的 ， 就 算 我 们 将 requirements.txt 与 发 布 的 程序 包 捆 绑 在 了 一 起 ， 计 算 机 仍 
EA Az ELS RAKA JE 

相反 ， 如 采 我 们 的 项 目 不 需 要 封装 ， 只 是 被 拿 来 当 作 一 个 Web JIwHWEHRS ER, ux 
必要 使 用 setup.py 了 。 在 项 目 从 开发 到 正式 上 线 的 过 程 中 ， 有 许多 程序 库 和 应 用 程序 要 一 个 版 
本 用 到 底 ， 因 此 我 们 要 严格 地 指定 版 本 。 而 对 于 不 需要 发 布 也 不 需要 封装 的 项 日 ，setup.py 就 失 
去 了 用 处 。 对 这 些 项 目 而 言 ， 用 requirements.txt 效率 更 高 。 

创建 requirements.txt 的 命令 如 LIST 3.59 所 示 。 























加 LIST 3.59 创建 requirements .txt 


(.venv)$ pip freeze > requirements.txt 


requirements.txt 中 记载 者 当前 环境 内 已 安装 的 所 有 程序 包 及 明确 的 版 本 号 (LIST 3.60 )。 





加 LIST 3.60 requirements.txt 


Elsesk 010 
Urb ga--o 3 
MarkupSafe-z0.23 
Werkzeug-z0.9.6 
guestbook] 0 


itsdangerous--0.24 





用 setup.py 管理 依赖 包 时 ， 我 们 只 写 了 Flask 但 没有 指定 版 本 。 这 是 setup.py 管理 和 
requirements.txt 管理 的 一 大 区 别 。 

要 想 在 其 他 环境 安 竣 同样 的 程序 包 们 ， 我 们 需要 将 这 个 requirements.txt 文件 放 到 该 环境 下 ， 
然后 用 如 LIST 3.61 所 示 的 方法 安装 。 


Ej LIST 3.61 用 requirements.txt 进行 安装 


(.venv)$ pip install -r requirements.txt 


这 样 一 来 ， 环 境 中 就 安安 了 同样 版 本 的 程序 包 。 
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现在 将 创建 好 的 requirements.txt 文件 也 提交 到 版 本 库 。 男 外 ， 当 我 们 变更 依赖 包 时 要 记得 
更 新 这 个 文件 。 请 各 位 打开 README.rst 文件 ， 将 变更 依赖 库 时 的 流程 更 新 成 如 LIST 3.62 所 示 
的 内 容 O 


© LIST 3.62 README.rst 
开发 流程 


1. SW ^^setup.py^^ ÉJ^^install requires^^ 
2. 按 以 下 流程 更 新 环境 : : 


(.venv)$ virtualenv --clear .venv 
(.venv)$ pip install -e ./guestbook 


(.venv)S$ pip freeze > requirements.txt 


3. 将 setup.py 4l requirements.txt 提交 到 版 本 库 


在 这 个 流程 中 ,依赖 包 同时 被 setup.py 和 requirements.txt 两 个 文件 管理 着 。 至 于 该 用 setup. 
py 管理 还 是 requirements.txt 管理 ， 要 视 项 目的 公开 方式 或 使 用 方式 而 定 。 








3.3.10 python setup.py bdist_whee| 一 一 制作 用 于 wheel 发 布 的 程序 包 


接 下 来 ,我 们 制作 wheel 程序 包 。wheel 程序 包 的 使 用 方法 在 9.1 节 有 详细 讲解 。 
制作 wheel 程序 包 之 前 ， 我 们 先 安 装 wheel( LIST 3.63 )。 


© LIST 3.63 ZJX wheel 


$ pip install wheel 

Downloading/unpacking wheel 
Downloading wheel-0.24.0-py2.py3-none-any.whl (63kB): 63kB downloaded 
Installing collected packages: wheel 
Successfully installed wheel 


Cleaning up... 


安装 完成 之 后 ， 我 们 就 可 以 用 bdist _ wheel 命令 了 。 接 下 来 ， 我 们 执行 python 
setup.pybdist wheel 来 生成 wheel 程序 包 (LIST 3.64 )。 
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© LIST 3.64 生成 wheel 程序 包 


$ python setup.py bdist wheel 

running bdist wheel 

- (中间 省 略 ) - 

creating  build/bdist.linux-x86 64/wheel/guestbook-1.0.0.dist-info/WHEEL 


$ Is dist/ 
guestbook-1.0.0-py2-none-any.whl questbook-1-0-0-tar.gz 


执行 完 之 后 ，dist 目录 下 就 会 生成 guestbook-1.0.0-p2-none-any.whl。 这 个 扩展 名 为 “.whl” 
的 文件 就 是 wheel 程序 包 。 在 wheel 程序 包 内 ， 按 照 安 猴 后 的 目录 结构 捆绑 了 源码 和 各 种 文件 。 
与 源码 程序 包 不 同 ， 它 里 面 没 有 setup.py。 

现在 只 要 将 这 个 文件 复制 到 等 待 安装 的 环境 中 ， 我 们 就 可 以 执行 pip install guestbook- 
1.0.0«Dp2-none-any.wlLL, 直接 从 文件 进行 安装 了 。 由 于 这 时 不 需要 运行 setup.py, 所 以 会 
EET FE FP BLIS KREE D HY T RC 


























Universal Wheel : 同时 支持 Python2 和 Python3 的 wheel 程序 包 
我 们 将 Python2 系列 和 Python3 系列 都 可 以 用 的 wheel 程序 包 称 为 Universal Wheels 
刚才 我 们 生成 的 程序 包 是 guestbook-1.0.0-p2-none-any.whl， 从 名 字 上 就 可 以 看 出 ， 这 个 

程序 包 是 对 应 Python2 的 。 由 于 guestbook 同时 支持 Python3， 所 以 我 们 在 Python3 下 执行 上 

述 流程 时 ， 会 生成 名 为 guestbook-1.0.0-p3-none-any.whl 的 wheel 文件 。 

如 果 想 生成 Universal Wheel 程序 包 ， 就 需要 在 bdist wheel 后 面 加 上 --universal 选项 ， 
代码 如 下 。 
$ python setup.py bdist wheel --universal 
-- (中 间 省 略 ) - - 
$ ls dist 
guestbook-1.0.0-py2.py3-none-any.whl 
当 程 序 包 仅 由 纯 Python 代码 实现 时 ， 会 生成 Universal Wheel。 而 在 诸如 需要 二 进 制 构建 、 
Python 实现 方面 受 限 等 情况 下 ， 则 无 法 生成 Universal Wheels 


3.39.11 上 传 到 PyPI 并 公开 
我 们 之 所 以 能 用 pip 命令 安装 指定 的 程序 包 ， 是 因为 这 些 包 都 被 注册 到 了 PyPI 上 。PyPI 是 
Python 的 官方 网 站 ， 所 有 人 都 能 随意 上 传 及 下 载 Python 程序 包 。 如 果 各 位 不 介意 公开 自己 开发 
的 程序 包 ， 不 妨 将 它 注 册 到 PyPI 上 。 
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举 个 例子 ， 如 果 我 们 要 安装 一 个 已 经 在 PyPI 上 注册 的 程序 包 bpmappers， 那 么 只 需 执行 





pip install bpmappers 即 可 。 








PyPI WEHA KT 8 A 2E ACEE QU] P ARIA SR. ASIE. EWE] PyPI 的 程序 包 无 法 只 


对 特定 用 户 公开 ， 所 以 各 位 要 千 万 注意 ， 别 把 对 外 保密 的 程序 库 注 册 上 来 。 


NOTE 


在 这 种 情况 下 ， 我 们 可 以 在 公司 内 部 准备 一 台 PyPl 交换 服务 器 ， 或 者 找 其 他 等 价 的 方法 。 


这 类 方法 我 们 将 在 第 9 章 中 详细 介绍 。 


下 面 我 们 就 把 已 做 好 的 程序 包 文 件 注册 到 PyPI。 如 果 想 在 实际 注册 之 前 先 注册 到 测试 服务 





器 ， 可 以 参考 本 节 的 专栏 “PyPI 的 测试 服务 器 ”。 


执行 register 命令 ， 注册 guestbook 程序 包 ( LIST 3.65 )。 


© LIST 3.65 注册 程序 包 


$ python setup.py register 


如 打发 生 下 述 情况 ， 执 行 register 命令 时 会 被 询问 是 否 拥 有 PyPI 账户 。 


e 该 环境 第 一 次 执行 register 命令 
o 保存 账户 信息 的 .pypirc 文件 无 效 








发 生 上 述 情况 时 ， 我 们 会 接 到 如 LIST 3.66 所 示 的 账户 询问 信息 。 


回 LIST 3.66 ”注册 程序 包 时 的 账户 询问 


$ python setup.py register 


running register 


We need to know who you are, so please choose either: 


ies 
zi 
DE 
4. 


use your existing login, 
register as a new user, 
have the server generate a new password for you (and email it to you), or 


Gilt 


Your selection [default 1]: 





如 果 各 位 已 经 有 PyPI 账 户 ， 请 选 1 并 输入 用 户 名 和 密码。 如 果 没 有 ， 则 需要 先 去 PyPI 网 





站 创建 账户 之 后 再 选 1， 要 么 就 是 直接 选择 2 或 3。 这 步 操作 会 认证 我 们 的 PyPI 账户 ， 只 要 认 
证 成 功 ， 我 们 就 可 以 使 用 register fI upload 命令 操作 PyPI T. 
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在 .pypirc 上 保存 密码 时 的 注意 事项 
在 输入 完 用 户 信息 、 即 将 完成 注册 时 ， 系 统 会 询问 是 否 将 登录 信息 保存 在 主 目录 的 “.pypirc 
文件 中 。 如 果 输 入 Y， 计 算 机 会 自动 生成 “.pypirc” 文 件 ， 以 纯 文 本 形式 保存 用 户 名 和 密码 。 
因此 ， 我 们 最 好 采取 一 些 对 策 ( 比如 设置 权限 等 )， 防 止 “.pypirc ”文件 的 内 容 被 第 三 者 窃取 。 
另外 ， 从 Python 2.7 开始 ， 我 们 可 以 用 编辑 器 将 保存 后 的 “.pypirc” 文 件 的 password 栏 
设置 为 空 栏 。 此 后 再 进行 上 传 时 ， 只 要 用 zegister upload 命令 代替 单独 的 upload 命令 ， 
就 可 以 做 到 仅 执 行 时 验证 密码 。 


ÉRE LA, WA pE PyPI 上传 程序 包 了 。 执 行 下 述 命令 之 后 ,源码 程 序 包 就 会 被 上 传 
至 PyPI, 





$ python setup.py sdist bdist wheel upload 





刚才 我 们 单独 执行 了 sdist 命令 和 bdist wheel 命令 。 其 实 如 上 例 所 示 ， 只 要 在 命令 末 
尾 指定 upload 命令 ， 就 可 以 在 封装 sdist 和 bdist wheel 程序 包 之 后 直接 将 它们 设 为 上 传 对 象 。 

绝 大 部 分 情况 下 ， 一 个 项 目 每 次 发 布 的 程序 包 类 型 都 基本 一 致 。 因 此 ， 我 们 可 以 把 注册 新 
版 本 、 构 建 程序 包 、 上 传 这 一 系列 流程 整合 成 一 个 命令 。 整 合 多 条 命令 时 ， 需 要 用 到 alias 功 
能 ， 代 码 如 下 。 








$ python setup.py alias release register sdist bdist wheel upload 
$ python setup.py release 





alias 命令 会 把 设置 你 存在 setup.cfg 中 ， 所 以 我 们 要 把 这 个 文件 也 提交 到 版 本 库 里 。 共 至 
alias 可 以 一 定 程度 上 避免 项 目 其 他 成 员 在 发 布 时 出 现 失误 。 





PyPI 的 测试 服务 器 

如 果 严 格 执行 本 书 中 的 流程 ， 各 位 的 guestbook 程序 包 就 会 被 实际 注册 到 PyPI 上 。 但 这 上 毕 
竟 是 一 个 练习 ， 我 们 不 建议 各 位 向 PyPl 服务 器 注册 这 些 练习 性 质 的 东西 ( 请 在 PyPI 网 站 搜索 printer )。 

所 以 ， 请 各 位 在 练习 时 使 用 PyPI 的 测试 服务 器 TestPyPI o TestPyPI 是 一 个 对 所 有 人 开放 
的 服务 器 ， 专 门 用 来 供 人 们 做 实验 。 我 们 可 以 用 它 来 练习 向 PyPl 上 传 程序 包 以 及 从 PyPl FE 
程序 包 。 

具体 使 用 方法 请 参考 TestPyPI 的 说 明 页 面 “。 


(D https://testpypi.python.org/pypi 
2) https://wiki.python.org/moin/TestPyPI 
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图 描述 程序 包 的 详细 信息 

上 传 完 成 后 ，PyPI 会 给 该 程序 包 分 配 一 个 URL。 例 如 guestbook 程序 包 的 URL 是 
https://pypi.python.org/pypi/guestbook。 另 外 ，setup.py HJ long description 传 值 参 
数 所 指定 的 内 容 将 会 显示 在 PyPI 页 面 上 。 

以 刚才 编写 完成 的 setup.py 为 例 来 看 ， 我 们 会 发 现 PyPI 页 面 上 只 显示 了 下 载 文件 的 列表 ， 
并 没有 任何 详细 说 明 。 这 是 因为 我 们 并 没有 指定 long description。 要 知道 ， 除 了 下 载 列 表 之 外 ， 
还 有 很 多 对 使 用 者 有 帮助 的 信息 ， 所 以 我 们 应 该 将 这 些 信息 摘 述 在 setup.py 中 ， 让 人 们 能 在 
PyPI 上 看 到 它们 。 下 面 是 一 个 描述 示例 。 





import os 


lom gs eoolsnpobc el na Cea 


cie eeu is JbeEs bes eme) t 
basepath osama nan tile _ )) 
filepath = os.path.join(basepath, filename) 
if os.path.exists(filepath): 
return open(filepath).read() 
else: 


em 


setup( 
name-'guestbook!, 
versrone-*'i 0-0 
description-'A guestbook web application.', 
long_description=read_file ('README.rst'), 
une 
author email='< 你 的 邮箱 地 址 »', 
url-'https://bitbucket.org/« fff'jBitbucket k »/guestbook/', 


classifiers=|[ 
'Development Status :: 4 - Beta', 
'Framework :: Flask', 
'License :: OSI Approved :: BSD License', 
'Programming Language :: Python', 
LProdgrsamumasng-banguadge Python 2 7 


] 

packages-find packages(), 

st rmeulabre (S Toxeretieeue le Noa I IS) 
keywords-['web', 'guestbook'], 
lu censes pope censes 

install requires-[ 


'Flask', 
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], 
entry pointg=""u 
[console scripts] 


guestbook = guestbook:main 


yx HUS HA AF 4 Pe 


e long description 

可 描述 多 行 说 明 。 说 明 内 容 按照 reStructuredText(reST) 语 法 进行 描述 ，PyPI 会 将 其 自动 转 
换 为 HTML 并 显示 在 网 站 上 。long description 的 内 容 大 多 和 README.rst 相 同 。 即 便 不 
同 ， 我 们 也 建议 各 位 将 长 达 几 行 的 说 明文 草 存放 在 其 他 文件 中 。 在 上 面 的 例子 里 ， 我 们 
设置 了 让 long description /RREADME.rstX- fF 

classifiers 

从 trove classifiers 定 义 的 项 目 中 选取 适当 项 目 ， 以 列表 的 形式 列举 在 这 里 。 这 个 列表 包含 
的 项 目 就 是 程序 包 在 PyPI 上 的 分 类 。 用 户 可 以 在 PyPI 网 站 上 通过 分 类 入 选 来 寻找 目 己 想 
要 的 程序 包 。 

在 上 面 的 例子 里 ， 我 们 摘 述 了 许可 证 信息 和 Python 版 本 等 。 如 采 我 们 想 指 定 的 分 类 并 不 
在 trove classifiers 之 中 ， 那 么 指 不 指定 它 都 无 所 谓 。 














e keywords 
以 列表 形式 列举 出 多 于 搜索 的 单词 ， 或 者 让 使 用 者 一 眼 就 明日 意思 的 词汇 。 
e license 


可 随意 描述 许可 证 信息 。 前 面 我 们 只 能 用 trove classifiers 定 义 过 的 值 来 指定 classifiers， 但 
license 处 却 可 以 指定 任意 字符 串 。 在 上 例 中 ， 我 们 将 这 部 分 描述 为 BSD License; 








这 里 只 对 一 部 分 会 显示 在 PyPI 上 的 setup 函数 的 传 值 参 数 进行 了 介绍 ， 此 外 还 有 许多 这 里 
并 未 提 及 的 传 值 参数 。 





Python 官方 文档 
https://docs.python.org/2.7/distutils/setupscript.html#additional-meta-data 











€ 检查 setup 函数 内 指定 的 参数 

将 程序 包 实际 上 传 到 PyPI 之 后 ， 我 们 需要 打开 PyPI 页 面 查 看 一 下 效果 。 如 果 发 现 页 面 并 
没有 将 long description 的 内 容 转换 为 HIML， 而 是 直接 显示 了 reST 文本 ， 和 那么 很 可 能 是 我 们 
HJ reST 摘 述 出 现 了 错误 。 为 回避 这 一 问题 ， 最 好 在 upload 之 前 查 一 过错 。 碍 错时 可 以 用 
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docutils 附属 的 rst2html .py 命令 。docutils 是 一 个 文字 处 理工 具 ， 它 能 将 reST 文本 转换 成 其 
他 多 种 格式 。 其 安装 方法 如 下 。 


$ pip ingtall cocuctile 











AC. docutils 后 ， 用 下 述 方法 执行 rst2html.py 命令 ， 查 看 文档 内 是 否 有 错误 描述 。 


$ python setup.py --long-description | rst2html.py » /dev/null 





另外 ， 如 采 各 位 使 用 的 是 Python 2.7 以 上 的 版 本 ， 并 且 环 境 中 安装 了 docutils， 那 么 可 以 用 
下 述 简短 的 命令 来 查 钳 。 文 档 没 有 问题 的 情况 下 只 会 显示 running check， 有 问题 则 会 显示 
类 似 下 例 的 内 容 。 





$ python setup.py check -r -s 

running check 

warning: check: No directive entry for "spam" in module "docutils.parsers.rst. 
languages.en". 4 


Trying "spam" as canonical directive name. (line 19) 
warning: check: Could not finish the parsing. 


error: Please correct your package. 





check 命令 用 于 检查 setup KA SŽ e Be 1E. "RA GG SESAETH E. AR 
会 报错 或 者 发 出 警告 。 我 们 只 要 给 check 命令 指定 儿 个 选项 ， 就 可 以 检查 long description 中 
指定 的 文本 是 否 符合 reStructuredText 语法 了 。 

这 个 检测 命令 也 可 以 添加 到 我 们 前 面 提 过 的 alias 设置 当中 ， 具 体 如 下 例 所 示 。 





$ python setup.py alias release check -r -s register sdist bdist egg upload 


这 样 一 来 ， 在 我 们 执行 python setup.py release 命令 时 ， 系 统 就 会 先进 行 checks —H. 
check 发 现 问题 ， 后 续 的 register 命令 将 不 再 执行 ， 有 问题 的 程序 包 也 就 不 会 被 发 布 出 去 了 。 


f£ PyPI 上 公开 

不 知 各 位 有 没有 这 样 一 种 感觉 : 在 PyPl 上 公开 了 程序 包 的 Python 工程 师 都 是 大 和 牛 1 

“ 写 好 程序 之 后 ， 先 整理 成 Python 的 标准 发 布 形 式 ， 然 后 公开 到 PyPl E, iESTEERA S 
用 !” 这 话说 起 来 容易 ， 但 真正 做 起 来 时 ， 许 多 人 会 不 禁 感到 犹豫 。 原 因 主要 有 两 个 ， 一 来 是 不 
知道 怎么 生成 标准 的 发 布 包 ， 二 来 是 认为 自己 写 的 程序 别人 拿 去 也 没什么 用 。 当 然 可 能 还 有 心 
理 上 的 抗拒 ， 觉 得 PyPl 上 面 满 满 的 都 是 世界 顶尖 好 用 的 程序 ， 目 己 写 的 程序 难 登 大 雅之 萌 ， 没 
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资格 发 布 在 PyPI E. 

354A, REA E B. XE PyPI ECITPRFPRBEIBSECAADJXEHAUE? 3x BR ZA 
因 人 而 异 ， 但 绝 大 多 数 人 的 出 发 点 无 外 乎 “和 希望 得 到 程序 的 反馈 信息 ` “和 希望 能 帮 到 别人 “向 
Python 工程 师 同行 们 炫耀 一 下 ”“ 想 听 到 别人 的 夸赞 ”之 类 。 另 外 ， 我 们 平时 也 会 隔 三 差 五 地 
向 PyPI 上 传 几 个 程序 包 ， 而 一 直 支 持 我 们 的 动机 则 是 “ 想 为 组 织 或 企业 做 宣传 "“ 想 让 大 家 知 
道 ， 让 大 家 拿 去 用 ”"”“ 很 多 自己 平时 用 的 OSS 都 来 自 这 里 ， 所 以 想 把 自己 做 出 的 成 果 也 放 在 这 
SS AH — P ARA o 

ARER, "QRübdnJA" "AEXSGCRRU" "XEfXAu iX—OIAULEP&)!RaABeá,PSPBHRhhN iXH, "UT 
想 让 全 世界 的 工程 师 看 自己 出 丑 ” 的 心理 因素 只 是 一 小 方面 ， 更 大 的 原因 是 这 个 阶段 能 完善 我 
们 的 程序 库 ， 使 其 回 到 一 个 干净 的 状态 ， 避 免 在 日 常 开 发 的 过 程 中 混入 一 些 多 余 功能 。 当 然 ， 
公开 后 多 得 的 反馈 也 是 其 购 力 之 。 

不 但 个 人 编写 的 程序 如 此 ， 工 作 中 开发 出 来 的 程序 同样 是 这 个 道理 。 拿 我 们 BePROUD 来 
说 ，bpmappers 和 bpss! 就 是 例子 。 因 为 它们 向 一 般 公 众 公 开 ， 所 以 要 维持 适当 的 功能 和 文档 。 
我 们 同时 还 收 到 了 公司 内 外 两 方面 的 反馈 ， 这 让 我 们 能 不 断 作出 改进 。 

所 以 ， 让 我 们 都 来 做 在 PyPI 上 公开 了 程序 包 的 Python 工程 师 大 牛 吧 。 这 对 技术 上 的 要 求 
并 没有 各 位 想象 中 那么 高 。 


3.3.12 “人 小结 


发 布 采 用 Python 编写 的 程序 库 或 应 用 程序 时 ， 最 标准 的 方法 就 是 用 setup.py 进行 封装 。 经 
setup.py 封装 后 的 发 布 包 要 注册 到 PyPI 上 ， 然 后 其 他 用 户 就 可 以 通过 pip 轻松 地 安装 了 了 。 夯 外 ， 
对 于 一 些 不 打算 公开 的 程序 ， 我 们 也 建议 将 其 封装 成 可 发 布 的 状态 ， 这 样 既 能 方便 地 放 到 其 他 
环境 下 试 运行 ， 又 能 便于 其 他 项 目 拿 去 重复 利用 。 此 外 还 要 养 成 一 个 习惯 ， 即 在 README.rst 
文件 中 写 明 项 目 概要 、 运 行 方法 、 设 置 等 信息 ， 以 便 重 复 利 用 程序 包 。 

如 果 各 位 还 想 进 一 步 了 解 setup.py 的 写法 或 封装 的 相关 知识 ， 可 以 参考 Python Packaging 
User Guide, 


Python Packaging User Guide 
https://packaging.python.org/en/latest/ 
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3.4 小结 





本 章 我 们 学 习 了 Python 项 目的 结构 ， 以 及 如 何 对 使 用 PyPA 工具 的 开发 环境 进行 设置 。 为 
外 ， 我 们 对 第 2 章 编 写 的 程序 进行 了 结构 调整 ， 同 时 学 习 了 如 何 把 程序 包 上 传 至 PyPI。 

对 于 要 经 常 重建 环境 的 情况 (例如 自动 测试 或 回 服务 需 部 署 ) 而 言 ， 本 章 介 绍 的 上 传 流程 
更 能 发 挥 其 效果 。 另 外 ， 从 下 一 章 开 始 ， 我 们 的 介绍 重点 将 从 个 人 开发 转移 到 团队 开发 ， 而 这 
里 学 习 的 流程 对 团队 开发 同样 有 效 。 




















团队 开 妈 的 周期 


在 第 2 部 分 中 ， 我 们 将 学 习 团 队 开 发 中 必 备 的 思路 ， 以 及 一 些 文 持 团 队 开发 
的 技术 和 工具 。 本 部 分 以 多 人 同时 作业 为 前 提 ， 内 容 涉及 多 人 协同 开发 所 必须 的 
堆栈 及 源码 共享 、 文 档 的 编写 、 单 元 测试 、 封 装 、 持 续集 成 等 方面 。 


第 4 章 面向 团队 开发 的 工具 
$$ 53x IWEBtIBÓtui 
第 6 章 用 Mercurial 管理 源码 


第 7 章 完备 文档 的 基础 

第 8 章 模块 分 割 设计 与 单元 测试 
第 9 章 Python 封装 及 其 运用 

第 10 章 用 Jenkins 持续 集成 





第 4 章 面向 团队 开发 的 工具 


前 面 我 们 用 3 革 的 篇 幅 学 习 了 个 人 如 何 搭 建 开 发 环境 以 及 开发 应 用 。 独 立 开 发 的 时 候 ， 保 
存 源码 等 工作 完全 可 以 按照 目 己 于 欢 的 方法 来 ， 而 且 各 种 信息 和 点 子 直 接 写 到 日 己 的 笔记 本 上 
NAT o 

那么 ， 一 个 由 多 人 组 成 的 团队 应 该 如 何 进行 开发 呢 ? 首先 ， 开 发 出 来 的 成 品 需要 在 所 有 成 
员 间 共享 。 然 后 ， 还 要 有 一 个 用 来 测试 开发 成 品 的 环境 。 另 外 ， 需 求 和 撤 术 等 信息 也 必须 共 且 
给 所 有 成 员 ， 而 且 成 员 间 交流 的 场所 也 必 不 可 少 。 

本 章 将 以 提高 团队 开发 效率 为 目的 ， 为 各 位 介绍 团队 开发 环境 的 搭建 过 程 以 及 一 些 有 用 的 
THe 
































4.1 问题 跟踪 系统 





要 想 让 团队 开发 顺风 顺水 ， 首 先 就 要 把 握 每 个 开发 任务 的 负 贡 人 是 谁 、 开 发 进展 到 了 什么 
程度 等 信息 ， 并 把 这 些 信息 整理 起 来 。 在 这 类 任务 管理 工作 上 ， 问 题 跟踪 系统 (Issue Tracking 
System, ITS ) Zé—3B2f-F-. 

我 们 可 以 将 开发 中 的 任务 添加 到 问题 跟踪 系统 ， 然 后 用 该 系统 来 据 蹊 、 管 理 这 些 任 务 的 状 
态 。 多 数 问题 跟 踩 系统 会 以 问题 ( Ticket ) 为 单位 进行 项 目 管 理 。 一 般 情 况 下 ， 我 们 会 把 工作 任 
务 以 问题 的 形式 水 加 到 问题 跟 踩 系统， 而 不 是 单纯 拿 它 来 管理 项 目 。 

问题 跟踪 系统 可 以 给 问题 添加 状态 (新 建 、 进 行 中 、 和 解决、 结束、 驳回 等 )， 设 置 优先 级 
( 紧急、 高 、 普 通 、 低 )、 负 责 人 、 日 期 等 ， 并 且 人 允许 用 户 通过 搜索 查看 信息 一 览 ， 让 我 们 能 随 
时 把 握 项 目的 开发 情况 。 

将 作业 分 割 成 一 个 个 任务 ， 再 将 任务 分 配给 问题 进行 管理 ， 这 种 开发 手法 称 为 问题 驱动 开 
发 (Ticket Driven Development, TiDD )。 它 与 敏捷 开发 有 着 很 好 的 相 容 性 ， 因 此 在 近年 来 的 开 
发 中 人 们 逐渐 开始 实践 这 种 手法 。 关 于 问题 跟 踊 系统 的 实际 运用 以 及 问题 驱动 开发 的 相关 知识 ， 
我 们 将 在 第 5 草 中 进行 学 习 。 









































4.1.1 Redmine 
接 下 来 ,我们 来 了 解 一 球 问题 跟踪 系统 





Redmine", Redmine 是 一 款 开 源 的 问题 跟踪 系 





(D http://www.redmine.org/ 
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统 ， 它 以 管理 项 目 内 的 任务 和 Bug 的 问题 功能 为 中 心 ， 兼 具 服 务 于 团队 开发 的 功能 ， 比 如 与 
Wiki 和 版 本 控制 系统 的 联动 等 。 


4.1.2 ”安装 Redmine 


现在 我 们 来 安装 Redmine, AORTAE Web ikir ( Apache) 和 Passenger ( 运行 Rails 
应 用 所 需 的 Apache 模块 ) ( LIST 4.1 )。 


© LIST 4.1 安装 Apache 


$ sudo apt-get install -y apache2 libapache2-mod-passenger 


Ac CRUISE MySQL ( LIST 42 ). 


© LIST 4.2 ”安装 MySQL 


$ sudo apt-get install -y mysql-server mysql-client 





在 安装 MySQL 的 过 程 中 ， 需 要 设置 MySQL 的 root 用 户 密码 (图 4.1, RI 4.2 )。 这 个 密码 
在 随后 安 闻 Redmine 时 会 用 到 。 





4.4 MySQL 的 密码 设置 





4.2 MySQL 的 密码 设置 ( 确认 ) 


接 下 来 安装 Redmine( LIST 4.3 )。 


B LIST 4.3 安装 Redmine 


$ sudo apt-get install -y redmine redmine-mysql 
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安装 过 程 中 会 显示 数据 库 设 置 的 相关 界面 ， 请 选择 “是 ”( 图 4.3 )。 





4.3 数据 库 设 置 
下 一 步 选择 我 们 要 使 用 的 数据 库 。 这 里 选 刚才 安 朔 的 MySQL( 图 4.4 ). 





4.4 选择 数据 库 
输入 MySQL 数据 库 管 理 员 的 密码 。 这 里 输入 刚刚 安装 MySQL 时 设置 的 密码 ( 图 4.5 )。 





4.5 管理 员 密 码 输入 界面 


最 后 设置 Redmine 专用 的 MySQL 应 用 密码 。 设 置 加 上 确认 ， 密 码 总 共 要 输入 两 这 (图 
4.6. BI 4.7 )。 
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4.6 设置 MySQL 应 用 密码 





4.7 确认 MySQL 应 用 密码 


至 此 ，Redmine 安装 完毕 


4.1.3 Redmine 的 设置 


要 想 通 过 Web 浏览 硕 访 问 Redmine， 需 要 更 改 Apache 的 设置 ， 所 以 接 下 来 我 们 修改 
Apache 的 设置 文件 。LIST 4.4 中 的 设置 将 这 个 Web IRI 281 EM [I Redmine 专用 。 


© LIST 4.4 修改 Apache 的 设置 文件 


S sudo vi /etc/apache2/sites-available/000-default.conf 


替换 000-default.conf 的 如 下 部 分 ( LIST 4.5 ), 


© LIST 4.5 000-default.conf 的 修改 


DocumentRoot /var/www/html 


l 


DocumentRoot /usr/share/redmine/public 


Redmine 需要 一 个 名 为 bundler 的 工具 ， 以 管理 Gem 包 ， 所 以 我 们 还 需要 安装 bundler 
(LIST 4.6 )。 


B LIST 4.6 安装 bundler 


$ sudo gem install bundler --no-rdoc --no-ri 


为 保证 我 们 能 通过 Apache 对 redmine 目录 下 执行 写 信 操作， 需要 修改 文件 的 所 有 权 
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( LIST 4.7 ), 


B LIST 4.7 ”变更 文件 的 所 有 权 


$ sudo chown -R www-data:www-data /usr/share/redmine 


至 此 ， 所 有 设置 结束 ， 我 们 重新 启动 Apache( LIST 4.8 )。 


© LIST 4.8 重启 Apache 


$ sudo service apache2 restart 


如 条 要 把 Redmine KREK OS 上 ， 人 然后 通过 本 地 环境 





CE OS ) 的 Web XI WEARI và, 7 TD , 


则 必须 设置 端口 转发 。 方 法 与 附录 B.2 一 样 ， 需 要 在 VirtualBox 的 端口 转发 设置 中 添加 一 行 设 
置 主机 端口 (TCP ) 8000、 子 系统 端口 80 (图 4.8 )。 


Oracle VM VirtualBox 管理 器 


d wo v 


新 建 (N) WES) MR 显示 (H) 





bpbook - 网 络 


D > Te 国 


存储 声音 网 络 端口 ”共享 文件 夹 




















8000 


用 户 界 面 


协议 主机 IP 主机 端口 子 采 统 IP 子 条 统 端 口 A 
2222 





Cancel 






网 卡 1: Intel PRO/1000 MT 桌面 (网 络 地 址 转换 (NAT)) 
_ 网 卡 2: Intel PRO/1000 MT 桌面 ( 仅 主 机 (Host-Only) 网 络 , 'vboxnetO") 













OK — 








\ | 
4.8 VirtualBox 5m 


现在 各 位 可 以 打开 浏览 器 访问 http://127.0.0.1:8000/， 看 看 是 


口 转发 设置 


的 界面 。 如 末 全 部 设置 正确 ， 各 位 应 该 会 看 到 如 图 4.9 WS. 





Ze 


伟 能 显示 出 Redmine 
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4.9 Redmine 的 初始 界面 


怎么 样 ， 看 到 Redmine 的 界面 了 吗 ? 
在 初始 状态 下 ， 管 理 员 只 要 在 用 户 名 和 密码 处 都 填 入 admin 即 可 登录 。 请 各 位 登录 管理 员 
用 户 ， 修 改 Redmine 的 各 项 设置 。 


4.1.4 插件 
Redmine 有 多 种 用 来 扩展 功能 的 插件 。 下 面 我 们 挑 几 个 比较 好 用 的 来 了 解 一 下 。 


€ Redmine reStructuredText Formatter 

Redmine reStructuredText Formatter 用 来 将 问题 和 Wiki 的 语法 从 标准 Textile 转换 为 
reStructuredText ( reST )。 

具体 使 用 哪 种 语法 ， 我 们 可 以 按照 团队 的 喜好 来 定 。 用 reST 描述 的 好 处 在 于 方便 用 Sphinx 
整理 文章 。 我 们 将 在 第 7 草 中 学 习 Sphinx 的 相关 内 容 。 





€ SCM Creator plugin 
使 用 SCM Creator plugin? 之后， 我们 就 可 以 通过 Redmine 给 项 目 创 建 版 本 库 了 。 


(D https://github.com/ebrahim/redmine restructuredtext formatter 


2) http://www.redmine. org/plugins/redmine scm 
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这 个 插件 的 安装 和 设置 请 参考 421. 


€ Slack chat plugin 
A Slack chat plugin ”之 后 ，Slack 聊天 系统 将 能 够 接收 Redmine 中 的 问题 更 新 通知 。 关 于 
Slack， 我 们 将 在 4.3 TÍT T Ho 





€ Issue Template plugin 

使 用 Issue Template plugin” 可 以 为 每 种 问题 分 别 设置 模板 , 以 便 开发 团队 成 员 明 白 哪 种 问题 
该 描述 些 什 么 。 比 如 ， 我 们 给 Bug 问题 设置 了 模板 后 ， 就 可 以 有 效 防止 源 记 项 目 。 

Issue Template plugin 的 安 疾 和 使 用 方法 请 参考 5.2 市 。 


4.2 版 本 控制 系统 





在 进行 团队 开发 时 ， 我 们 逢 要 一 个 地 方 来 集中 管理 和 共享 各 成 员 的 开发 成 果 。 男 外 ， 在 团 
队 开 发 的 过 程 中 ， 程 序 内 难免 混入 Bug， 这 就 需要 对 开发 成 末 进 行 历 史 管 理 ， 以 便 奶 踩 并 掌握 
Bug 混入 的 时 间 点 。 

在 这 一 点 上 ， 版 本 控制 系统 Version Control System, VCS) 能 提供 很 大 帮助 。 顾 名 思 义 ， 
版 本 控制 系统 就 是 用 来 管理 源码 等 内 容 的 开发 历史 的 。 当 今 的 版 本 控制 系统 主要 有 集中 式 的 
Subversion 和 分 布 式 的 Mercurial 、Git。 本 书 选 用 的 是 Mercurial. 

Redmine 和 Mercurial 都 是 面 回 团队 开发 的 工具 ， 这 里 将 学 习 如 何 把 它们 结合 在 一 起 使 用 。 
Mercurial 的 安装 与 简单 的 用 法 请 参考 第 1 草 ， 实 用 性 用 法 请 参考 第 6. 





























4.2.4 Mercurial 与 Redmine 的 联动 


如 果 让 版 本 控制 系统 和 问题 跟踪 系统 两 个 系统 联动 起 来 ， 可 以 明确 源码 的 变更 和 问题 之 间 
的 对 应 关系 ， 让 二 者 相得益彰 。 现 在 我 们 就 来 了 解 一 下 Redmine 和 Mercurial 的 联动 方法 。 

如 果 各 位 的 服务 锅 上 还 没有 安装 Mercurial， 那 么 需要 先 安装 Mercurial， 然 后 重启 Redmine 
(LIST 4.9 )。 


B LIST 4.9 安装 Mercurial 


$ sudo pip install mercurial 


$ sudo service apache2 restart 


(D https://github.com/sciyoshi/redmine-slack 
2 nhttp://www.r-labs.org/projects/issue-template/ 
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以 管理 员 刁 份 登 录 Redmine， 设 置 厂 本 控制 系统 。 
在 图 4.10 所 示 的 配置 界面 选择 “版 本 库 ” 标 签 页 ， 勾 选 “ 局 用 SCM” 中 的 相应 系统 然后 保 
存 。 这 样 我 们 就 可 以 使 用 选中 的 版 本 控制 系统 了 。 


管理 
一 般 || 显示 | | 认证 | | 项 目 | | amme || 邮件 通知 | | 接收 邮件 | | 版 本 库 NR 
& 用 户 
启用 SCM 学 组 
i» 角色 和 权限 
v ses 跟踪 标签 
Subversi Q svn » 问题 状态 
Darcs © darcs a 工作 流程 
© Mercurial wv hg 3.9 自 定义 属性 
cv O cvs 三 枚 举 值 
s 9 m P LDAP 认证 
Git Q git S 插件 
Filesystem 9 信息 
Github 


您 可 以 在 /etc/redmine/&lt;instance&gt;/configuration.yml 中 配置 您 的 SCM 命 令 。 请 在 编辑 后 ， 重 启 Redmine 应 用 。 


自动 获取 程序 变更 
启用 用 于 版 本 库 管 理 的 Web Service 


API key 生成 一 个 key 
在 文件 变更 记录 页 面 上 显示 的 最 大 修订 版 本 数量 100 


在 提交 信息 中 引用 和 解决 问题 
用 于 引用 问题 的 关键 字 refs,references,lssuelD 
可 以 使 用 多 个 值 (用 逗号 ,分 开 ) . 
允许 引用 /修复 所 有 其 他 项 目的 问题 
激活 时 间 日 志 
记录 的 活动 默认 人 


4.10 Redmine 的 版 本 库 配 置 界面 


4.2.2 ”用 于 生成 版 本 库 的 插件 


虽然 实现 版 本 控制 系统 的 联动 就 可 以 了 ,但 是 我 们 还 希望 能 直接 从 Redmine 创建 版 本 库 ， 
这 样 会 更 加 方便 。 为 此 ， 我 们 还 要 安装 SCM Creator plugin” 并 进行 设置 。 

首先 创建 一 个 用 于 生成 版 本 库 的 目录 C LIST 4.10 )。 这 里 我 们 用 的 目录 为 /var/lib/hg， 然 后 
更 改 它 的 所 有 权 ， 让 我 们 能 从 Redmine 对 它 进 行 写 人 操作 。 





© LIST 4.10 创建 用 于 版 本 库 的 目录 
$ sudo mkdir /var/lib/hg 


$ sudo chown www-data:www-data /var/lib/hg 


然后 创建 设置 文件 /usr/share/redmine/config/sem.yml ( LIST 4.11 )。 下 例 是 最 低 限 度 的 设置 。 
关于 设置 项 目的 详细 资料 ， 请 参考 该 插件 的 Web 页 面 。 


© LIST 4.11 scm.yml 


DEOductiom: 
deny ce ES fel ee 


autoccreate 3 True 


(D nttp://projects.andriylesyuk.com/projects/scm-creator 
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TOTE repository: talsge 
max repos: O0 
only creator, True 
allow acl local; relse 
allow _ pickup: false 
mercurial: 

path: /var/lib/hg 

hgs ncs Acc Abs 5 


插件 的 安装 流程 如 LIST 4.12。 需 要 先 将 下 载 好 的 插件 解压 到 Redmine 的 plugins HX F, 
然后 执行 rake 命令 构建 。 


© LIST 4.12 ”安装 SOM Creator plugin 


sudo mkdir /usr/share/redmine/plugins 

wget http://projects.andriylesyuk.com/attachments/download/563/redmine scm- 
vibe ado Dg 4 
sudo tar xfj redmine scm-0.5.0b.tar.bz2 -C /usr/share/redmine/plugins/ 

cd /usr/share/redmine/ 

sudo chown -R www-data:www-data plugins/redmine scm/ 


sudo rake redmine:plugins:migrate RAILS ENV=production 


SUs uUo uo xU x BY uw ue 


sudo service apache2 restart 


重启 apache2 后 ， 插 件 将 被 自动 加 载 。 我 们 可 以 在 图 4.11 所 示 的 配置 界面 里 看 到 插件 正常 
加 载 的 信息 。 


rsio ercurial, Bazaar and Github repositories within Redmine. Andriy Lesyuk — 0.5.0b 
e eator 


Allows creating Subversion, Git, M: 
http://projects.andriylesyuk.com/projects/scm-cr: 








4.11 Redmine 的 插件 配置 界面 


接 下 来 新 建 一 个 项 目 。 选 择 界面 左上 方 的 “项 目 ”， 人 然后 点 击 “ 新 建 项 目 ” 进 入 新 建 项 目 界 
面 ( 图 4.12 )。 要 记得 先 指定 SCM( 这 里 指定 为 Mercurial ) 再 创建 项 目 。 
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s» goo x 
gp cooo} 
a 
ooo 
z 








4.42. 新建 项 目 界 面 


查看 刚刚 创建 好 的 项 目的 配置 界面 ， 可 以 看 到 “版 本 库 ” 标 签 页 中 已 经 生成 了 Mercurial 的 
版 本 库 (图 4.13 )。 








主页 我 的 工作 台 项 目 管理 帮助 
bpbook 项 目 





4.13 ”版 本 库 配 置 界面 


至 此 ，Mercurial 与 Redmine 的 联动 就 实现 了 。 


43 ”聊天 系统 , 





在 团队 开发 中 ， 必 须 保 证 报告 、 联 络 、 探 讨 这 些 交 流 能 顺利 进行 。 说 到 交流 ， 一 般 不 是 面 
对 面 开 会 就 是 邮件 往来 ， 然 而 面对面 开会 时 ， 其 内 容 很 难 与 不 在 场 的 成 员 共 部 ， 而 邮件 又 难以 
保证 效率 。 聊 天 系统 则 能 扬长 避 短 ， 轻 松 实现 远程 实时 对 话 以 及 团队 内 信息 共享 。 

聊天 系统 种 类 繁多 ， 比 如 Skype. Slack, LINE, IRC 等 。 这 里 我 们 来 了 解 一 下 Slack”, 





4.3.1 Slack 


Slack 是 一 球面 向 企业 和 团体 的 交流 工具 。 除 了 可 以 进行 一 对 一 的 对 话 之 外 ， 还 能 创建 多 个 


(D https://slack.com/ 
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频道 、 内 部 群 组 等 聊天 室 ， 让 多 名 团队 成 员 同 时 参与 对 话 ( 图 4.14) 
这 项 服务 在 2013 年 才刚 刚 起 步 ， 但 由 于 其 导入 简单 、 使 用 方便 而 广 受 人 们 青睐 ， 如 今 已 被 
许多 企业 和 团体 使 用 。 





x 
BePROUD v @slackbot e = gg 
m Hi, Slackbot 
A This is the very beginning of your message history with Slackbot. Slackbot is pretty 

# random [M ! dumb, but tries to be helpful. 
* slackbot ] 

Tip: Use this message area as your personal scratchpad: anything you type here is 

private just to you, but shows up in your personal search results. Great for notes, 


addresses, links or anything you want to keep track of. 


E] For more tips, along with news and announcements, follow our Twitter account 
@slackhq and check out the £changelog. 


Tuesday, April 15th, 2014 


F 西 slackbot 
& Hi, Slackbot here! To make things easier for your teammates, | can set up a few personal details for 
you. 


To start, what is your first name? 
Pw tommy 
Yosuke 
slackbot 
Yosuke. Great! Now, what is your last name? 


a5 








4.14 Slack 


4.39. Slack 的 特点 
下 面 我 们 来 了 解 一 下 Slack 的 主要 特点 。 


€ 能 轻松 导入 的 Web 服务 

虽然 Slack 有 专用 的 客户 问 ， 但 其 很 大 程度 上 是 基于 Web 的 ， 所 以 能 脱离 客户 端 下 接 通 过 
DU aH. EMR IRC 那样 需要 准备 服务 硕 ， 再 加 上 采用 了 免费 增值 模式 ， 因 此 可 以 免费 使 
用 。 导 入 和 使 用 几乎 零 成 本 是 它 的 巨大 优势 。 

















@ 能 与 许多 外 部 服务 联动 

Slack 可 以 实现 与 许多 外 部 服务 的 联动 ( Integration )。 它 标 配 的 Integration 超过 60 种 ， 其 中 
包括 了 Dropbox、GitHub、Google Drive, Twitter 等 ， 我 们 可 以 从 设置 界面 轻松 地 开局 某 项 联动 
功能 。 联 动 的 内 容 因 服务 而 异 ， 以 Google Drive 为 例 ， 如 果 我 们 在 聊天 室 粘 贴 了 Google Drive 
上 的 文档 的 URL， 聊 天 室内 就 会 目 动 显 示 出 文档 的 标题 。 

Redmine 与 Slack 的 联动 可 由 Slack chat plugin for Redmine” 实现 。 这 是 一 个 要 用 到 Slack 
API 的 插件 ， 将 它 导 和 人 Redmine 之 后 ，Redmine WEI Slack 的 聊天 室 发 送 通 知 了 。 











(D https://github.com/sciyoshi/redmine-slack 
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除 Redmine 之 外 ，Jenkins、Sentry 也 可 以 加 Slack 发 送 通知 (图 4.15 )。Jenkins 直接 用 标 配 
的 Integration 即 可 。 如 果 使 用 Sentry， 则 要 给 Sentry 安装 sentry-slack 扩展 "。 





E à bpbook2015:bpbook2015 
bU 367228caf2d2 | 2014-11-18 19:11:26 +0900 | takayuki: update nit 





e jenkins 
P  bpbook2015 - 473 Failure after 25 £^ (Open) 


redmine 
[bpbook2015] shimizukawa updated 任务 #26646 准 备 开 发 环境 


说 明 

编写 准备 个 人 开发 环境 时 的 作业 流程 。 以 第 2 章 开发 的 应 用 为 对 象 貌似 不 错 。 
内 容 讨论 和 各 项 预 估 ( 38h 左 右 ) 

所 需 Python 开 发 环境 ( 6h ) 


进度 
30 








4.15 Slack 与 Redmine 和 Jenkins 的 联动 


通过 实时 显示 问题 的 更 新 、 加 版 本 库 的 提交 、Jenkins 的 构建 信息 等 ， 既 可 以 方便 我 们 和 掌握 
队 成 员 的 工作 情况 ， 又 可 以 保留 作业 日 志 ， 对 团队 开发 而 言 是 一 种 极 大 的 帮助 。 








@ 可 创建 bot 

Slackbot 是 Slack 标 配 的 bot。 这 个 功能 会 对 我 们 设置 的 关键 字 作 出 反应 ， 然 后 返回 特定 的 
消息 。 比 如 ， 如 有 果 和 布 望 在 有 人 说 “我 要 回 家 了 ”的 时 候 ， 目 劲 回答 “您 闻 百 了 ”这 人 句 话 或 者 别 
的 话 ， 只 要 在 Slackbot 中 进行 相应 设置 束 行 了 。 

如 果 想 进行 更 加 复杂 的 处 理 ， 可 以 用 Slack 附带 的 WebHook 功能 来 创建 自己 的 boto 

既然 是 目 己 的 bot， 那 它 的 用 处 就 全 看 我 们 的 创造 力 了 。 

举 个 例子 ， 假 设 我 们 在 Google Drive 的 电子 表格 里 存 了 测试 项 目 与 测试 结果 的 数据 一 览 。 
现在 每 次 查看 测试 进展 情况 都 要 打开 一 次 电子 表格 ， 实 在 太 麻 烦 ， 所 以 我 们 希望 这 一 流程 能 实 
现 自 动 化 。 这 时 就 可 以 创建 一 个 bot， 让 它 在 电子 表格 更 新 时 自动 获取 测试 结果 一 览 ， 并 提交 给 
Slack。 有 了 这 个 bot 之 后 ， 团 队 所 有 成 员 都 能 共 盏 测试 的 情况 ， 这 对 团队 开发 大 有 助 益 。 











€ 强大 的 @ 功能 加 速 团队 内 的 信息 传递 
Slack 有 着 强大 的 @ 功能 ， 这 个 功能 可 以 让 我 们 在 发 消息 时 指定 呼叫 某 个 用 户 。 如 来 在 我 
们 使 用 Slack 时 ， 有 人 发 消息 并 @ 了 我 们 ， 那么 聊天 室 列表 中 会 显示 通知 图 标 ， 告 诉 我 们 “有 





(D https://github.com/getsentry/sentry-slack 
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人 四 你 "。 如 采 我 们 当时 不 在 线 ， 该 消息 内 容 会 以 邮件 形式 进行 通知 。 另 外 ， 使 用 ioS 或 
Android 的 Slack 应 用 时 ， 通 知 会 显示 在 终端 的 通知 区 域 里 。 由 于 它 会 借助 各 种 通知 手段 来 通 
知 ， 因 此 我 们 很 难 漏 掉 那 些 @ 自己 的 信息 。 此 外 ，Slack 还 有 “@ 一 览 ” 功 能 ， 供 用 户 查 看 以 
往 所 有 @ 目 己 的 信息 。 

在 @ 别人 时 ， 用 户 名 输入 到 一 半 会 自动 弹出 用 户 名 候选 列表 ， 我 们 只 要 从 列表 中 选择 用 户 
名 即 可 。 这 样 一 来 既 可 以 节省 时 间 ， 又 能 防止 输 错 用 户 名 。 如 果 要 @ 聊天 室 中 的 所 有 人 ， 需 要 
用 @channel, @group 等 特殊 名 称 。 

正 因为 Slack 的 UI 发 @ 方 便 、 被 @ 醒 目 ， 所 以 很 少 会 出 现 “ 想 告诉 某 人 一 件 事 ， 结 果 某 
人 没 注意 到 ”这 种 沟通 失误 。 对 使 用 Slack 的 团队 开发 而 言 ， 这 绝对 是 一 大 优势 。 








€ URL 和 文件 的 预览 功能 

在 聊天 室 贴 URL 或 回 聊天 室 上 传 文件 后 ， 成 员 们 能 预览 其 内 容 。Web 页 面 的 URL 会 显示 
该 页 面 内 的 文本 ， 图 片 的 URL 则 会 显示 图 片 。 上 传 的 文件 也 是 同样 道理 ， 文 本 文件 会 显示 文 
本 ，jpg 或 png 等 图 片 文件 则 会 显示 图 片 。 

借助 于 这 一 功能 ， 我 们 能 很 轻松 地 与 团队 成 员 共 享 图片 形 式 的 信息 ( 比如 尚 在 开发 中 的 设 
计 方案 )。 








@ HMF 
除 上 述 这 些 之 外 ，Slack 作为 一 球 聊 天 系统 还 具备 许多 方便 的 功能 和 特征 。 


e 何洁 的 UI 

Slack 的 UI 设计 简洁 明了 ， 让 人 看 一 眼 就 能 上 手 使 用 。 虽 然 目 前 (2014 年 11 月 ) 只 提供 了 

英文 UI， 但 不 全 英语 的 人 用 起 来 也 不 会 有 什么 障 但 。 

可 该 性 高 的 text snippet 

用 户 可 以 用 text snippet 功 能 在 聊天 室内 粘贴 源码 。 这 些 源 但 会 以 语法 高 亮 的 形式 显示 。 

可 重复 利用 的 消息 记录 

Slack 会 给 每 一 条 消息 设置 永久 链接 ， 在 引用 消息 内 容 时 会 经 前 用 到 这 些 链 接 。 如 采 我 们 

想 引 用 某 条 消息 ， 只 要 在 Slack 中 粘贴 它 的 永久 链接 ， 该 消息 就 会 显示 在 聊天 框 中 。 这 一 

功能 让 我 们 的 销 息 不 再 转瞬 即 逝 ， 而 是 可 以 随时 拿 来 重复 利用 。 

e 类似 书签 的 星 标 功能 

如 有 果 有 想 关 注 的 聊天 室 或 者 怕 筷 记 的 消息 ， 那 么 可 以 给 它们 标 上 星星 。 我 们 可 以 在 星 标 
- 览 中 查看 标记 过 星星 的 信息 。 有 了 这 个 功能 ， 再 久远 的 消息 也 能 很 快 找到 。 

。 好 用 的 搜索 功能 

搜索 聊天 记录 的 功能 拥有 鉴 频 直 、 蜂 和 群 搜索 以 及 指定 日 期 等 多 种 选择 ， 能 很 轻松 地 找到 
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过 去 的 信息 或 附件 。 

。 "SII EH XE CT 
Slack EHI SJ B XE CRUS HI T BIDS 3441] 8I EASIER 2g 128 x 128 RJ H 
定义 表情 ， 还 可 以 添加 公司 或 产品 的 Logo， 这 给 我 们 带 来 了 意 想 不 到 的 便利 。 











@ 收费 版 
前 面 我 们 说 过 ，Slack 采用 了 人 免费 增值 模式 ， 所 以 用 户 可 以 免费 使 用 ,但 它 同时 还 提供 了 收 
3h Slack。 收 费 版 的 特征 如 下 。 


e 付费 
收费 版 会 根据 活动 用 户 数 量 收取 费用 。 

e 可 设置 单 频道 来 宾 
收费 版 可 创建 只 能 访问 一 个 频道 的 免费 来 宾 账户 ， 也 就 是 单 频道 来 宾 。 在 项 目 需要 临时 
与 团队 外 人 员 交 流 时 ， 有 单 频 道 来 宾 会 方便 许多 。 

。 不 限制 记录 保存 数 
介 费 版 只 可 以 保存 1 万 条 聊天 记录 ,但 收费 版 没有 这 个 限制 。 在 交流 频繁 的 时 候 ， 往 往 一 
天 会 出 现 几 百 条 消息 ，]1 万 条 记录 最 多 也 就 能 择 半 年 。 无 法 保存 记录 就 意味 看 我 们 无 法 参 
考 过 去 的 消 晨 ， 而 收费 版 就 不 用 担心 这 个 问题 了 了 。 

e 不 限制 Integration 
免费 版 只 能 添加 5 个 Integration， 但 收费 版 没有 限制 。 


























€ Slack 应 用 

Slack 为 OS X, iOS, Android 准备 了 专用 的 客户 端 。 只 要 在 各 个 系统 的 应 用 商城 中 搜索 
Slack ÀLBE 44 $1] ; 

网 页 版 的 Slack 不 支持 智能 手机 ， 所 以 10S 和 Android 要 想 使 用 Slack 必须 安装 应 用 。iOS 
和 Android 的 Slack 应 用 运行 起 来 更 快 ， 用 户 能 轻松 碍 看 消息 通知 和 发 送 消息 ， 而 且 新 的 消息 通 
知 会 发 送 到 OS 的 通知 区 域内 ， 不 用 担心 遗漏 重要 的 事情 。 

截止 到 现在 (2014 年 11 月 )，Slack 还 没有 Windows EHAR Ym, fH Google Chrome 的 
“创建 应 用 程序 快捷 方式 ”功能 可 以 创建 Slack 的 快捷 方式 ， 我 们 可 以 把 它 当 成 专用 客户 端 来 用 。 














4.3.8 Slack 做 不 到 的 事 


但 是 ，Slack 只 能 让 我 们 与 团队 内 部 成 员 交 流 。 当 我 们 需要 与 团队 外 (公司 外 ) 的 人 进行 交 
流 时 ， 必 须 将 对 方 邀 请 进 Slack 才 行 。 男 外 ， 有 些 时 候 让 团队 外 的 人 使 用 Slack As Erbe T EXE 
事 ， 因 此 可 以 考虑 把 Slack 和 普及 率 较 广 的 Skype 等 软件 结合 起 来 使 用 ， 以 便 与 团队 外 的 人 进 
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行 交流 。 
Slack 还 无 法 语音 聊天 。 有 些 商 讨 内容 打 字 聊 天 说 不 清楚 ， 而 语音 会 议 的 效果 会 好 很 多 ， 这 
种 时 候 就 可 以 拿 Skype 等 市 有 语音 聊天 功能 的 交流 工具 来 配合 使 用 。 

















4.3.4 Slack 的 注册 


Slack 的 注册 需要 在 https://slack.com/ 上 进行 。 虽 然 注 册 全 程 为 瑞 声 ， 但 中 间 要 输 
入 的 东西 也 就 是 邮箱 地 址 、 用 户 和 名、 团队 和 名、 专用 域名 、 邮 箱 域 名 、 密 人 码 而 已 ， 并 没有 什么 难 
的 。 创 建 团队 后 ，Slack 会 自动 分 配 一 个 专用 域名 给 我 们 ( 专用 域名 “.slack.com”)。 此 后 ， 我 们 
只 要 访问 这 个 地 址 ， 就 可 以 进行 登录 聊天 室 等 操作 了 。 

给 团队 设置 邮箱 域名 后 ， 所 有 拥有 该 域名 邮箱 的 人 都 可 以 创建 自己 团队 的 账户 。 比 如 要 在 
公司 里 用 Slack， 只 要 我 们 在 这 里 设置 了 公司 的 邮箱 域名 ， 公 司 成 员 就 都 可 以 创建 Slack 账户 了 。 


























4.4 ”对 团队 开发 有 帮助 的 工具 





在 前 面 几 方 中 ， 我 们 了 解 了 团队 开发 必 不 可 少 的 问题 跟 躁 系统 、 版 本 控制 系统 以 及 聊天 系 
统 。 除 此 之 外 ， 还 有 很 多 能 帮助 开发 团队 共 至 信息 和 数据 的 工具 。 这 里 我 们 来 了 解 一 下 其 中 的 
Dropbox 和 Google Drive。 











4.4.1 Dropbox 


Dropbox” 是 一 项 能 轻松 共享 开发 资料 等 文件 的 在 线 存 储 服 务 。 用 户 不 必 准 备 文件 服务 器 ， 
只 要 通过 Dropbox 即 可 与 团队 成 员 共 至 文件 。 由 于 其 前 期 工作 只 有 注册 用 户 这 一 步 ， 所 以 可 以 
省 去 搭建 及 使 用 文件 服务 需 的 成 本 。 各 位 可 以 把 它 看 作 一 个 网 络 上 的 文件 服务 需 。 

使 用 Dropbox 共享 文件 时 不 像 邮 箱 或 Skype 那样 烦琐 ,用 户 只 需 操 作 一 下 本 地 目录 ， 文 件 
就 会 自动 完成 同步 ， 这 可 以 为 我 们 市 省 大 量 时 间 。 男 外 ，Dropbox 允许 付费 增加 可 用 空间 ， 而 
且 为 用 户 准备 了 个 人 与 团体 两 个 不 同 使 用 方案 。 











4.4.2 Google Drive 


Google Drive? 是 Google EWM, Hio epe mE. Cun vas E 





(D http://www.dropboxchina.com/ 
2) https://www.google.com/drive/ 
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f Microsoft 的 Word, Excel, PowerPoint 等 软件 。 其 独特 之 处 在 于 允许 多 人 同时 编辑 一 个 文件 ， 
因此 可 以 在 文档 中 实现 交流 。 些 外， 用 户 可 以 详细 地 为 每 个 文件 设置 共享 用 户 及 权限 。 





4.5 小结 











本 革 重 点 在 于 了 解 面 癌 团 队 开 发 的 工具 ， 内 容 涉 及 问题 跟 踊 系 统 、 版 本 控制 系统 、 聊 天 系 
统 等 。 

如 果 我 们 能 够 灵活 运用 Mercurial 和 Redmine， 把 握 好 开发 成 果 及 信息 的 共享 环境 ， 束 可 以 
有 效 提 高 开发 效率 。 必 外 ， 信 助 Slack, Google Drive 等 工具 ， 我 们 可 以 通过 网 络 进行 交流 、 共 
至 信息 和 数据 ， 开 发 工作 不 再 受 场所 限制 ,减少 了 交通 和 交流 方面 的 成 本 。 

如 果 我 们 花 些 心思 学 会 使 用 工具 ， 还 能 有 效 地 提高 作业 效率 。 动 脑筋 提高 效率 同样 是 一 种 
乐趣 。 虽 然 团 队 开 发 中 的 交流 更 加 复杂 ， 但 我 们 可 以 通过 灵活 运动 工具 提高 沟通 效率 ， 从 而 做 
出 更 大 的 成 果 。 

















第 5 章 项 目 管 理 与 审查 


以 团队 形式 进行 开发 时 ， 应 该 避 循 什么 样 的 流程 呢 ?” 首 先 ， 要 分 配 作 业 任 务 ， 让 每 个 成 
员 负 责 一 部 分 开发 工作 。 每 天 或 每 周报 告 进度 ， 如 采 工 作 过 程 中 发 现 问题 则 必须 马上 共享 。 要 
想 更 好 地 管理 这 一 系列 流程 ， 使 开发 工作 更 加 顺利 ， 我 们 要 用 到 Redmine、Trac 这 类 问题 跟踪 
系统 。 

本 草 首 先 在 5.1 市 就 问题 跟 踊 系统 中 的 项 目 管 理 与 问题 的 区 分 使 用 进行 说 明 。 男 外 ， 会 在 
5.2 市 通过 实际 的 示例 讲解 如 何 统一 项 目 内 容 。 

然后 再 进一步 ， 将 问题 跟踪 系统 中 的 问题 与 厂 本 管理 系统 中 的 分 文 相 绪 合 ， 为 各 位 介绍 问 
题 驱 动 开 发 的 相关 知识 45.3 T) 

团队 开发 还 有 另外 一 项 优势 ， 那 就 是 在 分 配 任 务 和 实现 任务 之 余 ， 还 可 以 验证 当前 任务 或 
实现 是 否 正确 地 完成 了 ， 也 就 是 所 谓 的 审查 。5$.4 节 将 不 惜 大量 篇 幅 ， 为 各 位 讲解 审查 方 和 被 审 
查 方 各 目的 注意 事项 ， 以 及 一 些 行 之 有 效 的 审查 方法 。 





























5.1 项 目 管理 与 问题 的 区 分 使 用 


进行 项 目 管 理 时 ， 应 该 以 什么 为 单位 创建 问题 ， 每 个 问题 中 应 该 写 什 么 ， 这 都 是 整个 团队 
必须 统一 的 事 。 本 市 将 以 Redmine 为 例 ， 学 习 进 行 团队 项 目 管理 时 应 注意 的 一 些 点 。 





5.1.1 项 目 管 理 的 前 置 准备 工作 


在 Redmine 上 创建 项 目 、 开 始 项 目 管 理 之 前 ， 有 些 设置 需要 先 做 好 。 我 们 可 以 在 项 目的 
“配置 ”标签 页 进行 各 类 设置 (图 5.1 )。 











信息 || 模块 RA | 版 本 | 问题 类 别 || Wiki || 版 本 库 || 讨论 区 || 活动 (时间 跟踪 ) 


名 称 # bpbook 项 目 











保存 


@ 添加 成 员 


"FB rU sc mmm i ms»re m o 
标识 * bpbook 
主页 
公开 四 
上 级 项 目 ij 
继承 父 项 目 成 员 
跟踪 标签 
ge 错误 ge 功能 ge 支持 
5.1 项 目的 配置 界面 





首先 添加 参与 项 目的 成 员 。 成 员 按 职 责 不 同 分 为 3 种， 具体 区 分 如 下 。 


e 管理 人 员 : 


e 开发 人 员 
e REAR 


@ 添加 版 本 


一 个 项 目 必 然 存 在 确定 需求 、 实 现 完毕 、 
碑 的 信息 添加 到 厂 本 标签 页 ， 


版 本 设置 日 期 。 


@ 添加 问题 类 别 





可 更 改 项 目的 设置 。 一 般 情 况 下 所 有 项 目 成 员 都 可 以 设置 为 管理 人 员 


: 无 法 对 配置 界面 进行 操作 ， 其 余 操作 则 不 受 限制 。 通 第 是 公司 外 项 目 成 员 等 





: 测试 负责 人 ， 用 来 对 那些 负责 浴 加 问题 的 成 员 进 行 设置 





测试 完毕 等 阶段 点 〈 里程碑 )。 我们 要 把 各 个 里 程 
将 其 视 为 一 个 个 版 本 。 如 琳 版 本 发 布 日 期 已 确定 ， 则 可 以 给 相应 


如 朱 项 目 具备 一 定 规模 ， 那 么 最 好 以 功能 为 单位 添加 问题 类 别 。 座 加 类 别 时 ， 请 记得 设置 
该 尖 别 的 负责 人 。 在 没有 相应 负责 人 的 情况 下 ， 可 以 直接 将 项 目 组 长 设 为 负责 人 。 这 样 一 来 可 
以 避免 出 现 没 人 负责 的 问题 。 








5.1.2 创建 问题 


现在 我 们 已 经 做 好 了 给 项 目 创建 问题 的 准备 ， 可 以 实际 动手 创建 问题 了 。 点 击 “ 新 建 问 题 ” 
标签 会 出 现 如 图 5.2 所 示 的 界面 。 
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bpbook 项 目 sn | 
EE ED MRE S M Nit HHE nam ME xë P 2 E RE 
新 建 问题 
mus *(wx B 私有 
主题 * 
描述 BiZi U| sic m 2 B =Z c iB Fp aa 9 








状态 wit ES 
优先 级 ”| ma B 开始 日 期 2016-08-2( E] 
Nn B 计划 完成 日 其 a 
na 9 预期 时 间 小 时 
"nes Bo 9% 完成 0% B 
文件 “选择 文件 “未 选择 任何 文件 (最 大 尺寸 : 5 MB) 


跟踪 者 E 通过 查找 方式 添加 女 踪 者 


创建 。 创建 并 继续 ”预览 


5.2 新 建 问题 界面 
创建 问题 时 ， 各 项 目 按 如 下 内 容 输入 、 设 置 。 


内 容 


指定 问题 的 种 类 。 区 分 如 下 所 示 。 

。 功 能 : 用 于 实现 新 功能 的 问题 

e 错误 : 用 于 报告 Bug 

。 任务 : 实际 工作 、 操 作 等 

。 需求 讨论 : 用 于 讨论 需求 的 问题 。 需 求 确定 后 新 建功 能 问题 并 与 之 关联 


简洁 明了 地 描述 问题 的 内 容 

描述 这 个 问题 想 要 实现 的 内 容 。 用 问题 模板 ( Issue Template ) 统一 描述 内 容 后 可 有 效 防止 遗漏 
设置 问题 的 状态 。 比 如 开始 工作 后 选择 “进行 中 ”"， 工 作 完成 需要 别人 确认 时 选择 “反馈 ”等 
优先 级 如 果 描 述 的 内 容 比较 重要 ， 可 以 将 优先 级 提升 为 “高 ”或 其 他 

指派 给 选择 负责 这 个 问题 的 人 。 如 果 不 清楚 该 由 谁 负责 ， 可 以 指定 项 目 组 长 ， 再 让 项 目 组 长 更 改 为 适当 人 选 
指定 问题 的 类 别 ， 标 明 问 题 属于 哪个 部 分 、 与 什么 功能 相关 

如 果 项 目 中 存在 里 程 碑 ， 则 选择 “目标 版 本 ”这 一 项 

如 果 除 负责 人 之 外 还 有 其 他 人 员 与 此 问题 有 关 ， 则 选择 此 项 

在 此 添加 相关 图 片 或 文件 

要 与 父 任务 相关 联 时 ， 在 此 输入 父 任 务 的 编号 

添加 着 手 处 理 该 问题 的 日 期 。 可 直接 使 用 默认 日 期 ( 创建 日 期 ) 

计划 完成 日 期 望 在 哪 一 天 之 前 完成 此 问题 里 的 内 容 

预期 时 间 如 果 预 估 了 工作 时 间 ， 可 写 入 此 栏 


直接 用 0% 即 可 


(D 新 建 项 目 默 认 跟 踪 标 签 只 有 “功能 ” “错误 ”“ 支 持 ”3 项 ， 不 过 用 户 可 以 通过 管理 界面 里 的 “跟踪 标 
签 ”页 面 增加 、 删 除 和 修改 选项 。 这 里 的 “任务 ”和 “需求 讨论 ”应 该 是 作者 自己 创建 的 。 一 一 编者 注 






































5.1.3 整理 问题 


在 问题 中 描述 工作 内 容 ， 根 据 内 容 进行 操作 和 实现 ， 将 完工 的 问题 的 状态 改 为 “已 关闭 s 
当 这 一 系列 周期 顺风 顺水 时 ， 我 们 会 发 现 问题 一 个 个 减少 ， 有 一 种 项 目 同 着 成 功 迈 进 的 感觉。 

然而 ， 因 需求 变更 导致 问题 的 内 容 与 最 新 需求 产生 侦 差 ， 或 是 负责 人 设置 不 当 等 问题 经 稼 
会 导致 开发 无 法 进行 下 去 ， 结 打 就 是 无 人 问津 的 问题 越 积 越 多 。 一 旦 问题 堆积 起 来 ， 我 们 将 不 
知道 自己 还 剩 多 少 工作 要 做 ， 目 然 也 就 看 不 到 项 目的 终点 。 

为 防止 无 人 问津 的 问题 越 来 越 多 ， 我 们 需要 定期 整理 问题 。 问 题 的 整理 方法 如 下 。 


























D 问题 分 类 


按 更 新 顺序 重新 排列 未 结束 的 问题 。 更 新 日 期 较 早 的 问题 大 多 已 经 保 浏 ， 所 以 可 以 根据 


日 期 从 旧 到 新 进行 查看 。 
D 查看 问题 








碍 看 问题 里 与 的 工作 内 容 。 确 认 工作 内 容 与 实施 目标 是 否 一 致 ， 以 及 负责 人 旦 和 否 合适 。 
3) 结束、 驳回 问题 
如 有 果 发 现 内 容 与 其 他 问题 重复 ， 则 注 明 对 应 问题 编号 并 结束 当前 问题 。 如 果 工 作 内 容 与 
当前 需求 出 现 很 大 偏差 ， 则 写 明理 由 并 驳回 该 问题 。 
D 修正 问题 
如 末 工 作 内 容 不 明确 或 有 错误 ， 则 要 将 内 容 修正 至 能 正确 进行 为 止 。 如 采 工 作 内 容 涉及 
面 太 广 ， 同 时 出 现 多 名 负责 人 ， 则 可 以 按照 5.1.4 市 说 明 的 方法 进行 分 割 。 
© 分 配 问 题 
将 问题 指派 给 合适 的 负责 人 。 有 些 工作 内 容 会 涉及 多 名 人 负责 人 ， 此 时 要 根据 工作 优先 级 
挑选 出 一 名 主要 负责 人 。 




















要 是 等 问题 堆积 起 来 再 去 整理 ， 那 我 们 很 可 能 要 在 这 上 面 耗 上 一 整 天 ， 结 果 耽 误 本 来 该 干 
的 工作 。 建 议 各 位 平时 就 抽出 一 丁点 时 间 来 整理 它们 。 





5.1.4 分割 问题 


当 既 有 问题 久久 无 法 完成 时 ， 就 需要 我 们 重新 审视 该 问题 的 目标 了 。 因 为 我 们 在 创建 问题 
的 时 候 ， 很 可 能 没 注意 到 其 中 暗藏 的 大 量 工作 。 一 旦 遇 到 这 种 情况 ， 就 应 该 把 这 些 上 暗藏 的 任务 
分 割 到 其 他 问题 中 。 

这 样 一 来 ， 我 们 就 可 以 把 暂时 不 需要 处 理 的 内 容 回 后 放 ， 或 者 将 分 割 出 来 的 问题 交 给 其 他 
负责 人 。 另 外 ， 把 每 个 项 目 都 细 分 成 问题 还 有 助 于 管理 。Redmine 能 够 给 问题 添加 关联 ， 比 如 
父 置 父子 关系 ， 或 者 将 几 个 问题 设置 为 “相关 问题 ”等 ， 这 对 管理 的 帮助 很 大 。 











<- 
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当然 ,我们 也 可 以 在 最 开始 就 把 工作 细 分 成 较 小 的 问题 。 这 个 分 配 工 作 既 可 以 在 者 手 该 项 
目 时 进行 ， 也 可 以 等 到 必要 时 再 做 。 重 要 的 是 ， 要 根据 工作 量 以 及 工作 内 容 的 复杂 度 合 理 分 配 
任务 ， 然 后 整理 成 问题 。 





5.2 ”问题 模板 


我 们 在 5.1 了解 到 ， 新 建 问 题 时 要 在 “描述 ”一 栏 摘 述 这 个 问题 想 要 实现 的 内 容 。 不 过 
真 到 新 建 问 题 时 ， 我 们 往往 不 知道 该 写 些 什么 。 另 外 ， 一 旦 问题 的 描述 不 够 充分 ， 我 们 就 要 花 
费 很 多 时 间 在 留言 交流 上 。 

因此 ， 为 了 防止 问题 的 描述 出 现 遗 漏 ， 团 队 应 该 事先 统一 好 和 需要 描述 的 项 目 。Redmine 有 
一 个 插件 叫 问题 模板 ， 它 能 生成 统一 的 格式 (模板 ) 并 把 该 格式 反映 到 问题 中 。 

这 里 我 们 将 学 习 问 题 模 板 插件 的 使 用 方法 ， 然 后 给 各 位 看 一 个 实际 的 例子 。 








5.2.1 安装 插件 


要 想 给 Redmine 的 问题 设置 模板 ， 需 要 安装 Issue Template Plugin”, 
安装 插件 的 流程 如 LIST 5.1 所 示 。 


© LIST 5.1 Z3 Issue Template Plugin 


$ wget https://bitbucket.org/akiko pusu/redmine issue templates/downloads/redm 
ine igssue tcemolates-0. 0,9,719 J 
$ sudo mkdir /usr/share/redmine/plugins 

$ unzip redmine issue templates-0.0.9.zip -d /usr/share/redmine/plugins/ 

S cd /usr/share/redmine 

$ sudo chown -R www-data:www-data plugins 

$ sudo cp -pr plugins/redmine issue templates/assets public/plugin assets/redm 

ine _ issue _ templates d 
$ sudo rake redmine:plugins:migrate RAILS ENV=production 

$ sudo bundle install 


$ sudo service apache2 reload 











如 果 插 件 安 装 正确 ， 插 件 管理 界面 会 显示 Redmine Issue Templates plugin， 管 理 菜 单 中 将 多 
一 条 Global Issue Templates ( 全 局 问题 模板 ) ( 图 5.3 )。 


(D nttp://www.r-labs.org/projects/issue-template/ 
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Redmine 





插件 管理 


Redmine Issue Templates plugin $ 项 目 


Plugin to generate and use issue templates for each project to assist issue creation. Akiko Takano 0.0.9 局 用 户 
https://bitbucket.org/akiko pusu/redmine issue templates & 组 


i£; LDAP 认证 
9 Global Issue Templates 
e 信息 








5.3 Redmine 的 插件 管理 界面 


5.2.2 问题 模板 的 使 用 方法 
下 面 我 们 来 学 习 问 题 的 设置 和 使 用 方法 。 


@ 启用 问题 模板 功能 

打开 项 目的 “配置 ”一 “模块 ”界面 ， 勾 选 “ 问 题 模板 ”， 保存 后 即 可 对 该 项 目 开 启 问 题 模 
板 功 能 。 开 启 后 ， 配 置 界面 上 将 多 出 “问题 模板 ”标签 页 。 

男 外 ， 我 们 在 这 里 更 改 全 部 设置 ， 以 便 今后 创建 的 所 有 项 目 都 可 以 直接 使 用 问题 模板 功能 。 
打开 管理 界面 的 “配置 ”一 “项 目 ” 界 面 ， 在 “新 建 项 目 默认 启用 的 模块 ”中 色 选 “问题 模板 ” 
并 保存 (图 5.4 )。 





主页 我 的 工作 人 台 项 目 管理 帮助 登录 为 admin 我 的 帐号 退出 


Redmine 





配置 管理 
一 般 | | 显示 | | 认证 || ma || 问题 跟踪 || 邮件 通知 | | 接收 邮件 || 版 本 库 9 项 目 
& 用 户 
学 组 
新 建 项 目 默 认为 公开 项 目 D 角色 和 权限 
新 建 项 目 默认 启用 的 模块 回 问题 跟踪 本 跟踪 标签 
时 间 跟 踪 V) 问题 状态 
新 闻 a 工作 流程 
文档 自 定义 属性 
~ 
版 本 库 
讨论 区 . LDAP 认证 
日 历 © Global Issue Templates 
甘 特 图 Š 插件 
问题 模板 9 信息 
新 建 项 目 默认 跟踪 标签 回 错误 
功能 
支持 
顺序 产生 项 目标 识 


非 管 理 员 用 户 新 建 项 目 时 将 被 赋予 的 (在 该 项 目 中 的 ) ，--- 请 选择 --- 
角色 


保存 











5.4 管理 界面 的 项 目 配置 
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@ 创建 模板 
在 配置 界面 选中 “问题 模板 ”选项 卡 ， 上 点击“ 新建 ”进入 模板 添加 界面 (图 5.5 )。 





问题 模板 / 新 增 模板 列表 


模板 名 称 * 
用 于 该 问题 的 字段 : 
跟踪 标签 * ”错误 
问题 标题 Q 当前 字段 的 帮助 。 


模板 内 容 * B ru s c miu Hg iz Sm se am 9 

















批注 











默认 值 O 当前 字段 的 帮助 。 

启用 Q9 当前 字段 的 帮助 。 

Enabled sharing with ^ 49 当前 字段 的 帮助 。 
project tree. 


创建 ”预览 | 取消 


图 5.5 添加 问题 模板 的 界面 
请 按照 下 表 设 置 各 输入 项 目 。 
项 目 说 明 
模板 名 称 在 这 里 指定 问题 模板 的 名 称 。 我 们 规范 为 “用 于 OO 的 模板 ” 


跟踪 标签 在 这 里 指定 应 用 模板 的 跟踪 标签 的 种 类 功能、 错误、 支持 等 ) 


问题 标题 在 这 里 指定 标题 的 模板 











模板 内 容 在 这 里 输入 问题 内 容 模板 。 推 荐 使 用 标题 或 逐条 列 记 ， 这 种 模板 更 直观 易 用 
批注 不 需要 填写 

默认 值 勾 选 之 后 ， 选 择 该 类 问题 的 跟踪 标签 时 会 自动 套用 当前 模板 

局 用 勾 选 之 后 ， 该 模板 才 会 生效 

Enabled sharing with project tree. | 义 选 之 后 ， 子 项 目 也 可 以 使 用 该 模板 




















e 套用 模板 

问题 模板 的 使 用 方法 很 简单 ， 只 要 在 新 建 问题 界面 中 选择 模板 就 行 了 。 

选择 跟踪 标签 ( 问题 类 别 ) 后 ， 界 面 上 会 列表 显示 该 跟踪 标签 下 有 效 的 问题 模板 。 此 处 只 
要 选择 了 任意 一 个 模板 ,“ 主 题 ”“ 描 述 ” 就 会 被 自动 填充 。 随 后 我 们 只 需要 按照 通常 创建 问题 
的 步 又， 对 内 容 作 一 些 修 改 即 可 (图 5.6 )。 


主页 我 的 工作 人 台 ME 管理 帮助 





跟踪 fir 3 私有 
问题 模 村 Y --- Ə Clear subject and description text. 
主题 ， test template 1 | 
描记 test template 2 f "AE zz 3 B pre 2m Ə 














5.6 选择 问题 模板 


5.2.3 Global Issue Templates 





问题 模板 很 方便 ， 但 当 我 们 有 一 个 所 有 项 目 通 用 的 模板 时 ， 如 果 要 一 个 项 目 一 个 项 目地 去 
设置 这 个 模板 ， 那 可 不 是 一 般 的 抹 烦 。 这 种 时 候 ， 我 们 可 以 使 用 Global Issue Templates 功能 ， 
创建 一 个 所 有 项 目 通 用 的 模板 。 

创建 Global Issue Templates 时 ， 先 选择 Redmine 管理 界面 中 的 Global Issue Templates 菜单 ， 
然后 点 击 “ 新 建 模板 ”打开 如 图 5.7 所 示 的 界面 。 这 里 的 基本 输入 项 目 与 问题 模板 相同 ， 不 同 
点 则 是 下 面 多 出 了 “项 目 ” 区 域 。 这 里 会 显示 Redmine 上 的 所 有 项 目 ， 我 们 在 哪个 项 目前 面 打 
上 勾 并 保存 ， 该 模板 就 会 对 哪个 项 目 生效 。 

另外 ， 如 果 我 们 新 建 了 项 目 ，Global Issue Templates 并 不 会 自动 对 该 项 目 生 效 。 所 以 当 我 们 
创建 了 新 项 目 时 ， 需 要 打开 Global Issue Templates 的 编辑 界面 ， 勾 选 新 项 目 并 重新 保存 。 











?问题 模板 / 新 增 


模板 名 称 * 功能 问题 模板 


用 于 该 问题 的 字段 
跟踪 * 功能 B 
问题 标题 O 当前 字段 的 帮助。 


模板 内 容 *| B y uls c mmi 三 三 BJ" @ 9 





目的 
- 实现 该 功能 后 成 品 能 完成 什么 工作 ， 将 大 致 预 想 写 在 这 里 


- 需要 进行 回归 测试 的 地 方 
-生成 该 功能 所 需 数据 的 功能 《可 添加 与 对 象 ticket 的 关联 ) 











批注 | 


启用 O 当前 字段 的 帮助 。 


5.7 添加 Global Issue Templates 的 界面 
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5.2.4 问题 模板 示例 


这 里 ， 我 们 为 每 个 跟踪 标签 各 准备 了 一 个 问题 模板 的 范例 。 
我 们 用 的 格式 是 reStructuredText， 如 有 果 各 位 使 用 的 是 Redmine 默认 的 Textile， 请 目 行 作 相 
应 替换 。 


€ 功能 
与 添加 功能 相关 的 问题 ( LIST 5.2 )。 描 述 要 实现 何 种 功能 。 


加 LIST 5.2 功能 问题 的 模板 
目的 


将 
过 
x 
过 
me 
TES 
pn 
Eb 

H 


品 能 完成 什么 工作 ， 将 大致 预 想 写 在 这 里 


- 记录 输入 的 值 和 输出 的 结 


相关 功能 、 影 响 沁 围 


- 需要 进行 回归 测试 的 地 方 
- 生成 该 功能 所 需 数据 的 功能 ( 可 添加 与 对 象 问题 的 关联 ) 
- 使 用 该 功能 所 生成 数据 的 功能 ( 可 添加 与 对 象 问题 的 关联 ) 


- 如 有 安全 相关 问题 ( 权限 等 )， 则 将 相应 内 容 写 在 这 里 


SE 
E ES 


- 记录 URL 或 其 他 能 轻松 查看 该 功能 的 操作 流程 


€ 第 误 


用 于 报告 Bug 的 问题 (LIST 5.3 )。 将 试验 等 过 程 中 发 现 的 Bug 制作 成 问题 ， 分 配给 相应 负 


© LIST 5.3 错误 问题 的 模板 
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- 描述 出 现 该 Bug 的 操作 流程 


预期 结果 


- 描述 试验 环境 


示例 
= QS Ma OS XX EO 
- 浏览 器 : IE11 
TARE : admin 
- HH Bug fS URL : https://staging.example.com/very-critical-feature 


- 描述 错误 日 志 、 消 息 Sentry 的 URL 等 


e 任务 
关于 各 种 作业 的 问题 ( LIST 5.4 )。 


© LIST 5.4 任务 问题 的 模板 


义 行 该 任务 的 目的 


e 需求 讨论 
用 来 讨论 需求 的 问题 。 确 定 需求 后 关闭 这 个 问题 ， 然 后 新 建功 能 问题 ， 并 与 之 相关 联 。 








加 LIST 5.5 需求 讨论 问题 的 模板 (LIST 5.5) 
目的 
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- 当前 讨论 的 需求 要 达成 何 种 预期 。 


-记录 已 有 的 需求 方案 ， 有 多 种 时 可 记录 多 个 方案 
-同时 记录 优点 和 缺点 


- 记录 URL 或 其 他 能 轻松 查看 该 方案 的 操作 流程 


5.3 ”问题 驱动 开发 








接 下 来 我 们 来 学 习 问 题 驱动 的 团队 开发 。 


5.3.1 别 急 着 裔 代码 ， 先 建 问题 


下 面 我 们 开始 学 习 团 队 开发 的 一 系列 流程 。 所 请 开发 ， 既 可 以 是 开发 新 应 用 ， 也 可 以 是 修 
改 已 有 系统 。 重 要 的 是 ， 我 们 在 打开 编辑 融 裔 代码 之 前 ， 要 先 把 即将 着 手 处 理 的 项 目 座 加 到 问 
题 跟踪 系统 之 中 。 

在 Redmine 界面 中 填 入 标题 和 任务 概述 并 完成 洪 加 后 ， 我 们 将 得 到 一 个 带 有 编号 的 问题 
CIEE "42" ) (图 5.8 )。 





INIR IRDA 
。 附 元 搜索 功 能 
输入 输出 
。 显示 项 目 : 品牌 、 产 地 、 价 格 、 库 存 ( 


。 RESH: ME, me. NE ( 可 指定 Fr 
相关 功能 、 影 响 范围 
。 列表 时 示 的 姑 果 源 白 活 0 打 共 教 究 功 能 所 泛 


安全 


。 HSCERASRIP SIR 


5.8 Redmine 的 问题 界面 


5.3.2 ”创建 与 问题 编号 同名 的 分 支 


获得 问题 跟踪 系统 分 配 的 问题 编号 之 后 ， 我 们 就 可 以 在 Mercurial 上 创建 一 个 与 之 同名 的 分 
支 了 。 举 个 例子 ， 如 果 问 题 的 编号 为 “#100”， 那 么 我 们 的 分 支 名 就 对 应 为 “t100”。 

这 样 一 来 ， 我 们 负责 的 项 目 和 源码 的 修改 内 容 就 一 一 对 应 起 来 了 。 等 到 我 们 完成 了 这 部 分 
工作 ， 只 要 将 t100 分 文 合 并 到 default 分 文 ， 就 能 轻松 完成 发 布 工作 ， 十 分 方便 。 另 外 , 将 “一 
个 问题 对 应 创建 一 个 分 文 ” 用 作 项 目 方针 来 规范 团队 ， 可 以 有 效 减少 恼人 的 多 头 现象 4 Multiple 
Head， 即 最 新 端 变更 集 分 成 多 个 版 本 的 现象 )。 而 且 ， 由 于 问题 的 编号 与 分 文 名 一 一 对 应 ， 所 以 
当 我 们 想 查 看 项 目 #100 所 修改 的 内 容 时 ， 只 需 查 看 分 文 t100 即 可 ， 非 常 方 便 。 


























© 主题 分 文 与 问题 驱动 开发 

这 种 为 单一 问题 ( 主题 ) 而 创建 的 分 文 称 为 主题 分 文 。 

一 个 项 目 拥 有 的 主题 分 文 数 往往 很 怀 人 。 我 们 没 必 要 给 每 个 主题 分 文 和 都 起 一 个 有 意义 的 名 
字 。 人 花 大 量 时 间 在 起 名 字 上 ， 有 时 反而 会 起 出 一 些 让 人 摸 不 清 头脑 的 名 字 ， 倒 不 如 机 械 式 地 起 
名 来 得 方便 ， 而 且 不 会 出 现 皮 义 。 问 题 跟 踊 系 统 的 问题 ID 一 般 都 很 独特 ， 再 加 上 它 具 备 我 们 前 
面 提 过 的 那些 优势 ， 所 以 用 它 肯 是 万 无 一 失 。 

像 这 样 基 于 问题 跟踪 系统 的 问题 来 进行 开发 的 模式 就 称 为 问题 驱动 开发 。 





























明确 区 分 分 支 名 与 版 本 修订 号 

主题 分 支 的 英文 是 Topic Branch， 所 以 名 字 前 面 都 加 了 to Æ Mercurial 中 ， 这 还 起 到 了 区 
分 分 支 名 与 版 本 修订 号 的 重要 作用 。 仅 由 数值 组 成 的 分 支 名 很 容易 与 版 本 修订 号 搞 混 ， 弄 不 好 
就 会 出 现 意外 情况 ， 所 以 应 当 尽量 避免 使 用 仅 由 数值 组 成 的 分 支 名 。 


5.3.3 让 发 布 与 分 文 相 对 应 


从 项 目 管理 的 观点 讲 ， 我 们 提倡 设置 里 程 碑 并 制定 发 布 计划 。 而 采用 敏捷 开发 的 项 目 还 会 
基于 迭代 来 制定 发 布 计 划 。 

在 系统 开发 中 ， 发 布 计划 的 重要 性 不 言 而 喻 。 前 面 我 们 讲 了 问题 与 分 文 一 一 对 应 的 好 处 ， 
同样 着 理 ， 将 发 布 与 版 本 管理 系统 的 分 文 一 一 对 应 也 能 方便 管理 。 

使 用 Mercurial 时 ，default 分 文 是 一 个 既定 的 分 文 ， 必 然 存在 。 因 此 我 们 规定 “default = Ifi 
问 正 式 运 行 的 分 文 "。 然 后 假设 现在 有 一 个 发 布 ， 我们 从 default 创建 一 个 新 分 文 与 它 相 对 应 
( LIST 5.6 ). 
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B LIST 5.6 JA default 创建 发 布 分 支 


$ hg update default 
$ hg branca ml23 1 


然后 ， 基 于 新 创建 的 发 布 分 支派 生出 各 个 主题 分 支 ( LIST 5.7 )。 





E LIST 5.7 创建 主题 分 支 
$ hg branci 
md 9 
$ dare branca 让 二 0 


用 作 里 程 碑 的 分 文 并 没有 严格 的 命名 法 则 ， 但 为 了 表示 其 “里 程 碑 ”之 意 ， 我 们 用 字母 m 
11586 

m 后 面 可 以 是 发 布 日 期 (上 例 中 的 1231 表示 12 H 31 日 )， 也 可 以 是 明确 表示 发 布 的 特殊 
词汇 (比如 智能 手机 版 的 发 布 命名 为 mm smartphone 等 )。 由 于 问题 跟踪 系统 不 会 专门 给 里 程 碑 
分 配 特 殊 ID, ， 而 且 创建 里 程 碑 并 不 像 创建 主题 分 文 那 样 频 繁 ， 所 以 我 们 完全 可 以 给 每 个 里 程 碑 
设置 个 性 化 的 分 文 名 。 











5.3.4 ”分支 的 合并 
刚刚 我 们 通过 创建 分 支 将 开发 成 果 分 割 开 了 。 各 个 项 目 都 有 对 应 的 分 支 ， 分 支 之 间 的 开发 
和 提交 相互 独立 。 因 此 ， 当 项 目 完 成 后 ， 还 需要 将 它 合 并 回来 。 合 并 的 规则 很 简单 ， 保 证 只 合 
并 有 父子 关系 的 分 支 就 行 了 (图 5.9、 图 5.10 )。 








D 只 在 父 分 文 和 子 分 文 之 间 进 行 合并 。 
久子 分 支 之 间 不 合并 。 
O 从 子 分 文 派 生出 来 的 孙 分 文 不 能 二 接合 并 到 父 分 文 。 


上 述 规则 必须 严格 还 守 。 





( t10 ) 
( t11 ) 


59 父 分 支 与 子 分 支 之 间 的 合并 





图 5.10 “一些 应 当 避 免 的 合并 


如 果 合并 了 没有 父子 关系 的 分 支 ， 我 们 好 不 容易 分 割 清楚 的 项 目 会 再 度 乱 成 一 团 。 这 可 能 
会 导致 问题 里 没 提 到 的 修改 内 容 在 不 知 不 党 间 混 入 ， 或 者 导致 源码 产生 冲突， 等 等 。 想 在 其 他 








分 文中 反映 某 分 文 的 成 末 时 也 要 有 还 守 这 一 规则 ， 苑 与 它们 共同 的 父 分 文 合并 ， 再 反映 到 对 旬 子 
分 文 里 。 

虽然 这 样 做 很 麻烦 ， 但 在 父 分 文中 分 部 一 些 本 不 该 出 现 的 半成品 会 导致 很 多 问题 ， 所 以 请 
PNI DEEST 

只 要 按照 我 们 这 里 学 习 的 方法 创建 分 文 ， 一 般 不 会 遇 到 子 分 文 之 间 合 并 或 者 孙 分 文 问 父 分 
文 合 并 的 情况 。 如 末 无 论 如 何 虱 得 进行 这 类 操作 ， 那 就 可 以 认定 是 分 割 项 目 与 设置 父子 天 系 的 
阶段 出 现 了 问题 ， 需 要 我 们 修改 问题 的 内 容 或 选择 其 他 方法 应 对 。 

为 外 ， 在 将 子 分 文 合并 到 父 分 文 之 前 ， 一 定 要 多 在 子 分 文中 反映 父 分 文 的 修改 内 容 。 因 为 
在 我 们 修改 子 分 文 的 过 程 中 很 可 能 有 其 他 人 对 父 分 文 作 了 修改 ， 所 以 要 和 匈 将 这 部 分 修改 吸收 到 
我 们 的 子 分 文中 ， 保 证 “ 父 分 文 和 子 分 文 之 间 的 差别 = 我 们 对 子 分 文 作 的 修改 ”。 

这 样 一 来 ， 即 便 子 分 支 与 父 分 支 之 间 出 现 了 矛盾 ， 我 们 只 要 回 到 上 自己 的 任务 分 文中 就 能 解 
决 该 问题 。 























5.4.1 为 什么 需要 审查 


审查 的 意义 大 致 有 两 个 。 

一 个 是 修正 错误 。 通 过 审查 人 员 的 指正 ， 我 们 能 及 早 发 现 单 人 作业 时 忽略 的 问题 以 及 一 些 
错误 有 的 认识 。 

为 一 个 是 知识 共 圣 。 审 查 能 带 助 团队 成 员 分 至 在 工作 过 程 中 学 到 的 新 知识 ， 同 时 也 是 不 同 
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特长 的 成 员 相 互 交 流 和 守门 和 经 验 的 好 机 会 。 
这 里 我 们 了 解 一 下 “受审 查 者 在 接受 审查 时 ”和 “审查 者 在 进行 审查 时 ”的 注意 事项 。 力 
外 ， 本 市 将 审查 分 为 分 “源码 的 审查 ”和 “发 布 作业 的 审查 ”"， 分 别称 为 代码 审查 和 作业 审查 。 











5.4.2 ”审查 委托 : 代码 审查 篇 


@ 准备 资料 

接受 审查 前 站 和 完 要 准备 资料 。 将 目 己 写 代码 时 参考 的 规格 文档 、 和 需求 定义 文档 、 界 面 图 等 
资料 提供 给 审查 者 。 

同时 要 让 审查 者 清楚 日 己 修 改 了 哪 部 分 源码 。 我 们 可 以 列 出 源码 修改 前 后 的 差别 ， 让 审查 
者 对 修改 内 容 一 目 了 然 。 











@ 统一 编码 风格 

我 们 在 第 1 草 中 了 解 到 ，PEP8 这 种 编码 风格 如 今 被 人 们 广泛 采用 。 所 以 我 们 可 以 先 借助 
flake8 统一 编码 风格 ， 然 后 再 请 人 来 审查 。flakeg 的 使 用 方法 以 及 在 编辑 器 中 的 设置 方法 请 参考 
1.3 d. 

如 采 某 个 项 目 想 采用 与 PEP8 稍 有 不 同 的 编码 风格 ， 我 们 可 以 准备 出 一 个 设置 文件 (setup. 
cfg ) 来自 定 义 flake8 的 检测 内 容 。 

比方 说 我 们 想 将 一 行 的 最 大 限制 从 80 个 字符 提高 到 120 个 字符 ， 那 么 要 在 项 目 根 目 录 下 的 
setup.cfg 中 作 如 下 描述 ( LIST 5.8 )。 




















Ej LIST 5.8 setup.cfg 示例 


[£lake8] 
max-line-length - 120 


flake8 Configuration 
https://flake8.readthedocs.org/en/2.2.3/config.html 


这 样 一 来 ，flake8 SLE 120 个 字符 以 内 的 行 发 出 警告 了 。 变 更 项 目的 编码 风格 时 ， 记 
得 要 先 取得 项 目 成 员 们 的 一 致 同意 。 











@ 把 希望 审查 员 确 认 的 事项 整理 出 来 
接 下 来 思考 一 下 审查 时 的 步 又 。 漫 无 目的 地 检查 全 部 代码 既 耗 时 又 没 效 末 ， 所 以 要 圈 出 重点 。 
那么 应 该 如 何 圈 重 点 呢 ? 请 参考 以 下 2 个 原则 。 








(D 目 己 不 放心 的 地 方 
处 理 比较 复杂 或 者 涉及 卫生 模块 的 地 方 等 。 总 之 要 将 目 己 不 放心 的 地 方 交 给 审查 者 确认 。 
(2) 费心 设计 的 地 方 
回顾 一 下 实现 过 程 中 思虑 再 三 的 地 方 以 及 设计 上 比较 费心 的 地 方 ， 将 它们 总 结 并 整理 出 
来 。 这 些 需要 人 花 时 间 思 考 的 部 分 很 可 能 是 需求 或 设计 上 的 重要 部 分 ， 应 该 积极 地 交 给 审 
碍 者 检查 。 态 外 ， 将 编码 或 测试 中 的 难点 与 其 他 团队 成 员 共 主 也 是 一 件 有 利 无 敬 的 事 。 











@ 反映 审查 结果 
接受 审查 时 要 虚心 听取 指正 并 记录 下 来 。 另 外 ， 根 据 指正 进行 修改 后 还 要 请 审查 者 再 确认 
— ii o 














5.4.3 ”审查 委托 : PLIERS 


@ 准备 资料 
接受 作业 审查 时 也 需要 准备 相关 资料 。 尽 量 把 需要 负责 人 严格 把 关 的 事故 易 发 点 共享 出 来 
比如 服务 器 的 环境 设置 、 网 络 构架 等 














€ 制作 作业 流程 文档 
将 作业 总 结 成 “作业 流程 文档 ”。 制 作 该 文档 时 需要 注意 以 下 几 点 。 


CD 目的 和 概述 
写 出 该 作业 的 目的 或 概述 。 比 如 像 下 面 这 样 的 原因 或 问题 经 过 、 非 正常 作业 流程 等 就 要 
写 出 来 ， 让 审查 者 一 日 了 然 。 





e 由 于 编写 为 #123 的 问题 中 的 问题 导致 接 单 表 数 据 不 一 致 ， 为 修正 此 问题 进行 数据 维护 
。 发 布 面 回 营 业 的 接 单数 据 报 告 功 能 。 为 进行 发 布 作 业 而 更 改 数据 库 定 义 以 及 修改 
Apache 的 设置 





D 作业 场所 
写 明 是 在 哪里 进行 的 作业 。 在 正式 环境 由 多 台 服 务 太 共同 组 成 时 ( 比如 主 从 式 数 据 库 ) 
要 格外 注意 这 一 点 。 

© 所 需 时 间 与 时 间 规 划 
各 项 作业 的 预计 所 需 时 间 以 及 作业 整体 的 时 间 规 划 能 帮助 我 们 制定 当天 的 计划 。 另 外 ， 
当 外 部 相关 人 员 加 入 时 ， 我 们 还 可 以 根据 它 来 修改 日 程 。 

9 负责 人 
如 朱 事 先知 道 当 天 的 作业 负责 人 ， 了 最 好 把 负责 人 信息 记 下 来 。 同 时 要 写 明 进行 该 作业 的 
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是 团队 内 部 人 员 还 是 承包 方 负责 人 。 

© 执行 用 户 与 权限 
写 明 该 作业 由 OS 的 哪个 用 户 执行 。 这 样 就 可 以 避免 到 了 实际 作业 时 才 发 现 没有 root fX 
限 而 懂 了 手脚 。 这 对 写 流 程 文档 的 人 来 说 或 许 意 义 不 大 ， 但 当天 保 不 准 会 由 其 他 人 来 代 
替 我 们 进行 该 项 作业 ， 如 果 对 方 摘 不 清热 行 用 户 ， 将 很 容易 引起 麻烦 。 所 以 这 一 
记 上 为 妙 。 

(0) 执行 命令 
在 命令 行 执行 某 条 命令 时 ， 需 要 将 该 命令 记录 下 来 。 只 要 保证 作业 内 容 固定 ， 那 么 任何 
人 执行 该 作业 都 能 得 到 相同 结果 ， 造 成 问题 的 风险 也 就 相对 较 小 。 另 外 ， 执 行 命令 之 后 
要 检查 命令 是 否 正 党 执行 完毕 ， 这 个 检查 的 方法 也 最 好 写 在 这 里 。 

CD 作业 失败 时 的 对 策 以 及 补救 方法 
对 于 一 些 有 着 复杂 流程 的 作业 ， 或 者 一 旦 失败 就 难以 还 原 的 作业 ， 应 该 事先 写 明 失败 时 
的 还 原 方 法 。 事 先 准备 好 应 对 方法 能 避免 正式 作业 中 惰 手 懂 脚 。 

(8 试 运行 的 记录 
如 果 在 本 地 的 VM 上 进行 了 试 运行 ， 那 么 应 该 把 结果 记录 添加 在 这 里 。 试 运行 的 结果 不 
但 能 让 审查 者 对 正式 作业 有 一 个 更 清晰 的 印象 ， 还 能 帮助 审查 者 发 觉 正式 作业 时 需要 注 
意 的 点 。 


















































审查 者 要 根据 这 些 唤 料 判断 受审 查 者 的 开发 成 末 是 否 翌 当 。 





5.4.4 实施 审查 : 代码 审查 篇 


e 形式 上 的 检查 没有 意义 
如 采 把 有 限 的 时 间 花 费 在 检查 “一 行 有 多 少 个 字符 ”“ 类 或 亢 数 的 定义 之 间 空 了 几 行 ”等 问 
题 上 ， 那 完全 是 在 浪费 审查 时 间 。 这 些 事项 用 PEP8 或 pyflakes 等 lint 工具 就 能 轻松 搞定 。 
审查 时 要 把 时 间 花 在 以 下 几 个 项 目的 检查 上 。 























D 程序 是 否 满足 需求 
D 是 否 有 遗漏 需求 
D 设计 或 实现 的 效率 是 否 够 高 








© 发 现 疑 问 就 询问 理由 或 缘由 
Ce 
受审 查 者 在 接受 审查 时 不 一 定 能 把 这 些 情况 全 部 说 清楚 ， 而 审查 者 又 不 知道 对 方 源 说 了 哪 

















些 知 识 ， 所 以 审查 者 在 看 代码 时 第 常会 觉得 有 些 不 对 幼 。 作 为 一 名 审查 者 ， 我 们 必须 考虑 到 这 
种 情况 。 对 于 有 疑问 的 部 分 ， 要 问 受 审查 者 了 解 痛 景 或 绿 由 ， 然 后 努力 去 理解 。 如 末 我 们 有 更 
好 的 解决 方法 ， 要 当场 提出 。 





@ 整理 注释 

关于 源码 上 是 否 应 该 留 有 注释 ， 众 说 纷 颖 。 不 过 ， 我 们 建议 将 修改 程序 时 的 育 景 或 缘由 简 
单 地 注释 下 来 。 日 后 再 有 人 接触 这 部 分 源码 时 ， 很 可 能 会 对 该 项 处 理 抱 有 疑问 ， 而 注释 能 帮助 
他 们 理解 实现 者 的 意图 。 

但 这 并 不 是 说 所 有 地 方 都 要 留 注释 。 只 要 把 实现 过 程 中 需要 注意 的 难点 顾及 到 了 就 行 。 故 
外 ， 如 采 注 释文 的 篇 幅 实在 太 长 ， 最 好 改 用 文档 或 其 他 形式 保存 。 

反 过 来 ， 我 们 还 需要 检查 该 删除 的 注释 是 否 都 删除 了 。 因 需求 变更 而 修改 源码 后 ， 有 一 部 
分 注释 会 与 事实 不 符 ， 这 些 注释 就 知 要 删 去 。 














© 判断 是 否 需要 修正 时 ， 要 考虑 重要 性 和 日 程 之 间 的 平衡 

即便 我 们 断定 受审 查 者 写 的 代码 需要 修改 ， 也 要 考虑 修改 内 容 的 重要 性 以 及 日 程 。 很 多 时 
修 ， 代 人 码 修改 后 确实 能 提高 可 读 性 ,但 当 涉 及 的 代码 规模 很 小 时 ， 我 们 完全 可 以 不 对 本 次 代码 
作 修 改 ， 只 敦促 对 方 下 次 注意 即 可 。 相 对 地 ， 如 果 可 读 性 差 或 效率 低 的 代码 已 经 被 大 量 复制 和 
粳 贴 ， 那 就 很 可 能 对 今后 的 修改 造成 影响 ， 这 时 就 必须 千 促 对 方 修改 。 

不 过 ， 是 否 立 刻 修改 仍 有 商量 余地 。 有 时 考虑 到 日 程 所 限 ， 可 以 将 修改 程序 的 作业 创建 成 
问题 并 延 后 处 理 。 

















@ 将 编码 能 力 不 足 和 问题 意识 分 开 评 价 
有 些 时 候 ， 里 然 受 审查 者 的 编码 能 力 还 欠 火 候 ， 但 需求 和 设计 方面 的 问题 意识 可 圈 可 点 ， 
看 就 是 认真 考 夸 过 的 。 受 审查 者 日 然 布 望 获得 肯定 ， 所 以 这 种 时 候 我 们 要 充分 肯定 对 方 的 问 
锅 意 识 ， 只 针对 编码 方面 作出 指正 。 























rietveld 的 功能 介绍 

平日 里 ， 我 们 用 Mercurial 的 diff 进行 简单 审查 ， 同 时 会 还 配合 使 用 Google 开发 的 代码 审 
ALR rietveld。 这 个 专栏 将 对 rietveld 的 功能 作 简 单 介绍 。rietveld 是 在 Google App Engine 
上 运行 的 Web 应 用 式 代 码 审查 工具 。 

委托 别人 进行 审查 时 ， 要 将 审查 对 象 diff 提交 给 rietveld。 提 交 内 容 将 汇总 为 patch set 形 
式 ， 生 成 审查 专用 页 面 。 根 据 diff 的 内 容 ， 该 工具 会 生成 审查 对 象 文件 一 览 表 以 及 各 文件 的 审 
S o 
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v Patch Set 1 


Total comments: 6 





| Created: 3 months ago 
Unified diffs Side-by-sidi 
|> M .hgignore View 
| A source/book/chapterO02/guestbook/guestbook.py View 
A source/book/chapterO2/guestbook/static/main.css View 
A source/book/chapter02/guestbook/templates/index.html View 
v Messages 


Total messages: 5 
Expand All Messages | Collapse All Messages 
























































tokibito 

SHIMIZUKAWA 代码 干净 利 素 ， 完 全 不 像 初 学 者 写 的 ， 但 我 觉得 这 样 会 好 些 。 

tokibito 

SHIMIZUKAWA tokibito wrote: > > 教程 里 看 到 的 大 多 是 app， 以 后 要 用 application 吗 ? 
tokibito 


图 5.11 审查 对 象 文 件 一 览 表 


各 文件 的 审查 页 面 有 两 种 阅览 形式 (unified 形式 和 side-by-side 形式 ) (图 5.12、 图 5.13 )。 
ATEXEBUNUEX, TETEXS— 11 EXGEABRILATTJEES SEE, SÉASHOEEES ji (EA 5.14 ). 


« no previous file with comments | « .hgignore (k') | source/book/chapterO02/guestbook/static/main.css » (j') | source/book/chapter02/guestbook/templates/index.html » (J') 
Expand Comments (e) | Collapse Comments ('c') | Hide Comments (s) 


Index: source/book/chapter82/guestbook/guestbook.py 


new file mode 1800644 

--- /dev/null 

+++ b/source/book/chapter82/guestbook/guestbook.py 

ee -0,0 «1,79 ee 

+# coding: utf-B 

+import shelve 

+from datetime import datetime 

* 

*from flask import Flask, request, render template, redirect, escape, Markup 
* 

*application = Flask( name ) 

SHIMIZUKAWA 2011/09/09 07:11:27 

教程 里 看 到 的 大 多 是 app， 以 后 要 用 application 吗 ? 

Reply Done 

tokibito 2011/09/09 07:28:54 

Show quoted text 

用 modwsgi 可 以 直接 运行 ， 而 且 可 以 省 略 gunicorn 命 令 ， 所 以 我 们 一 直 在 用 application。 
Reply Done 

* 

«DATA FILE = 'guestbook.dat' 























图 5.12 unified 形式 的 审查 页 面 


OLD NEW 
fvim:fileencoding-utf-B 
from datetime import datetime 


1 fvim:fileencoding-utf-8 


1 
2 
2 3 
3 from django.contrib import admin 4 from django.contrib import admin 

4 from django.contrib import messages 5 from django.contrib import messages 

5 from django.contrib.auth.decorators import permission required 6 from django.contrib.auth.decorators import permission required 
6 from django.core.urlresolvers import reverse 7 from django.core.urlresolvers import reverse 

7 from django.views.generic.simple import direct to template 8 from django.views.generic.simple import direct to template 

8 


from django.http import Http404, HttpResponseRedirect 9 from django.http import Http404, HttpResponseRedirect 
9 from django.shortcuts import get object or 404 18 from django.shortcuts import get object or 404 
18 from django.utils.decorators import method decorator 11 from django.utils.decorators import method decorator 
11 from django.views.decorators.csrf import csrf protect 12 from django.views.decorators.csrf import csrf protect 
12 from django.conf import settings 13 from django.conf import settings 
13 from django.db import transaction 14 from django.db import transaction 
14 at 15 from django.db.models import Count 
15 from django.forms Form 16 from django.conf.urls.defaults import patterns, url 








me 2010/11/02 7:39:01 确认 是 否 真 的 可 以 删 去 


SHIMIZUKAWA 2010/11/02 08:15:50 不 能 删 去 ! RRIT | 






5.13 side-by-side 形式 的 审查 页 面 


* 


*from flask import Flask, request, render template, redirect, escape, Markup 





4annliratian ~ Flackí nama ) 


图 5.14 可 以 直接 在 代码 中 添加 留 


i 


rietveld 这 类 工具 虽然 会 增加 审查 的 前 置 准 备 工 作 ， 但 它 可 以 高 效 审查 涉及 多 个 文件 的 大 幅 
度 更 改 ， 而 且 不 必 审 查 者 和 被 审查 者 同时 在 场 。 根 据 审 查 对 象 的 不 同 ， 我 们 可 以 选择 用 工具 进 
行 审 查 ， 或 者 用 diff 甚至 是 打印 出 来 的 源码 进行 审查 ， 从 而 提高 审查 效率 。 


€ 能 否 跟踪 作业 内 容 和 实施 历史 

不 论 事 前 事后 ， 我 们 都 硕 望 能 够 客观 笃 握 负责 人 的 作业 情况 ， 所 以 要 督促 对 方 将 作业 内 容 
以 流程 文档 等 形式 保留 下 来 。 在 服务 侣 或 数据 库 上 作业 时 则 要 记录 已 执行 的 命令 或 SQL 语句 。 
为 外 ,命令 的 执行 结 玉 也 要 记录 下 来 。 这 样 一 来 ， 即 便 事 后 才 发 现 作 业 失 误 或 者 作业 内 容 不 周 
E, 我们 也 可 以 根据 记录 查找 原因 ， 制 定 对 荣 进 行 弥 补 。 




















e 能 否 还 原 ， 是 否 有 备份 

作业 失败 时 能 进行 还 原 是 十 分 重要 的 。 

比如 这 个 作业 要 进行 数据 库 的 数据 修正 ， 如 果 我 们 发 现 事务 忘记 了 BEGIN， 直接 发 出 了 
UPDATE 语句 ， 那 么 必须 指正 出 来 。 同 样 地 ， 数 据 库 备 份 的 重要 性 也 是 不 言 而 喻 的 。 


€ 是 否 受 外 部 因素 的 影响 

即便 受审 查 者 在 写 流程 文档 时 制定 了 受 当 的 作业 流程 ， 实 际 作 业 仍 可 能 受到 一 些 与 作业 内 
容 没 有 朋 接 关系 的 外 部 因 系 影响 而 失败 。 

比如 以 下 这 些 情况 。 























e 发 布 对 象 程序 需要 调用 外 部 API 时，API 方 有 访问 限制 ， 但 程序 没有 申请 解除 限制 
e 发 布 服务 时 ， 没 有 将 维护 消息 通知 给 用 户 。 或 者 维护 时 间 过 又 ， 每 次 都 是 人 勉 蝇 完 成 维护 
e 去 记 停 止 正式 服务 融 的 cron 中 设置 的 定时 任务 ， 在 作业 中 诈 执 行 了 批 处 理 ， 从 而 引起 问题 











审查 者 要 注意 这 类 外 部 因 系 的 有 无 。 


5.5 小结 


本 革 先 讲解 了 使 用 问题 跟踪 系统 时 的 注音 点 。 
接 下 来 对 把 项 目 管 理 与 版 本 管理 结合 起 来 的 问题 驱动 开发 进行 了 介绍 。 问 题 与 分 文 相互 配 
合 管理 有 助 于 开发 顺利 进行 。 夯 外 ,这样 做 还 能 有 效 减 少 源码 的 黎 导 ， 让 我 们 在 团队 开发 时 不 
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必 为 此 费心 。 

至 于 审查 ,我 们 从 被 审查 者 和 审查 者 两 个 角度 出 发 , 分 别 了 解 了 其 知 要 注意 的 地 方 。 我 
们 前 面 也 说 过 ， 能 够 进行 审查 是 团队 开发 的 一 大 优势 。 但 是 ， 如 末 审 碍 时 抓 不 住 重点 ， 那 就 审 
查 很 可 能 沦 为 形式 上 的 检查 。 乔 望 各 位 能 熟 记 本 章 讲述 的 这 些 注 意 点 ， 去 实践 一 些 更 有 意义 的 
审查 。 























第 6 音 用 Mercurial 管理 源码 


Mercurial 是 我 们 公司 标 配 的 版 本 控制 系统 ， 公 司 的 日 党 业务 大 多 离 不 开 它 。 

除 前 面 几 章 提 到 的 提交 、push、pull、 创 建 分 文 等 基本 操作 之 外 ，Mercurial 还 具备 许多 功 
。 有 灵活 运用 这 些 功能 能 帮助 我 们 在 各 种 情况 下 顺利 完成 开发 。 

本 章 将 重点 讲解 Mercurial 的 使 用 窗 门 ， 包 括 一 些 好 用 的 功能 、 版 本 库 的 管理 方法 、 各 种 工 
具 等 ， 帮 助 各 位 进一步 惑 练 使 用 Mercurial. 








anb 
GG 





6.1 Mercurial 版 本 库 的 管理 与 设置 


Mercurial 是 分 布 式 版 本 管理 系统 ， 所 以 原则 上 是 不 需要 Subversion 那 种 中 央 版 本 库 的 。 
但 是 ， 开 发 团队 成 员 之 间 共 胖 成 采 〈 变 更 集 ) 时 ， 如 果 仅 挺 对 等 (Peer To Peer) 方式 进行 交 
流 ， 效 末 是 十 分 有 限 的 。 为 解决 这 一 问题 ， 需 要 在 所 有 开发 成 员 都 能 随时 访问 的 服务 硕 上 设 
置 一 个 中 央 版 本 库 ， 用 它 来 共 吝 成 末 。 接 下 来 将 要 介绍 的 ， 就 是 在 服务 硕 上 设置 中 央 版 本 库 
的 步 又 。 




















6.1.1 服务 器 上 的 Uinx 用 户 群 设置 


要 想 对 文件 系统 上 的 Mercurial 版 本 库 进行 操作 ， 必 须 能 在 对 象 版 本 库 内 的 “.hg” 目 录 下 
进行 谈 写 ， 这 就 需要 相应 的 访问 权限 。 因 此 ， 用 版 本 库 进行 开发 的 Unix 用 户 需要 设置 为 同一 用 


户 群 来 集中 管理 。 
我 们 创建 名 为 dev 的 群 作为 本 例 的 开发 者 群 (LIST 6.1)。 这 需要 以 管理 员 权 限 执行 
groupadd 命令 。 


© LIST 6.1 创建 dev 群 


$ sudo groupadd dev 
然后 用 useradd 命令 给 dev 群 新 建 用 户 ， 用 户 名 指定 方法 如 LIST 6.2 所 示 。 


Ə LIST6.2 ”新 建 dev 群 的 用 户 


$ sudo useradd -g dev «username» 


即 通过 username» 指定 用 户 名 。 
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NOTE 
jE mn aed ST D» Gel] ese lox 
指定 -s 选项 可 以 设置 登录 时 使 用 的 shell。 





另外 ， 回 群 中 添加 已 有 用 户 时 要 用 usermod 命令 (LIST 6.3 )。 
EJ LIST 6.3 向 dev 群 添加 已 有 用 户 


$ sudo usermod -a -G dev «username» 


NOTE 
用 户 群 的 修改 内 容 不 会 对 已 登录 服务 颖 的 用 户 立 刻 生效 。 直 到 下 次 登录 时 才 会 应 用 新 的 群 。 


6.1.2 创建 版 本 库 


由 于 服务 器 上 要 放 好 几 个 版 本 库 ， 所 以 我 们 新 建 一 个 统一 存放 版 本 库 的 目录 。 本 例 的 路 径 
为 /var/hg/( LIST 6.4 )。 各 版 本 库 要 在 这 个 目录 下 创建 。 





Ej LIST6.4 创建 /var/hg/ 目录 
$ sudo mkdir /var/hg/ 
接 下 来 我 们 在 这 个 目录 下 新 建 一 个 版 本 库 。 执 行 hg init 命令 ， 新 建 名 为 testrepo 的 版 本 
库 (LIST 6.5 )。 


© LIST6.5 创建 testrepo 版 本 库 
$ sudo hg init /var/hg/testrepo 
然后 把 版 本 库 内 “.hg” 目 录 的 所 有 权 交 给 dev BE, ib dev 群 的 用 户 能 够 对 该 版 本 库 进 行 写 
入 操作 C LIST 6.6 )。 


回 LIST 6.6 将 版 本 库 的 群 改 为 dev 
$ sudo chgrp -R dev /var/hg/testrepo/.hg 


另外 还 需要 设置 SGID (Set Group ID )， 保 证 问 版 本 库 写 入 时 ， 文 件 的 所 有 者 是 dev TE 
( LIST 6.7 )。 


© LIST 6.7 设置 SGID 


$ sudo chmod g+sw -R /var/hg/testrepo/.hg 
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这 样 我 们 就 有 了 一 个 可 多 用 户 共 同 使 用 的 版 本 库 。 


6.1.3 hgrc 的 设置 


要 想 在 服务 器 问 执 行 钧 子 (Hook) 脚本 ， 必 须 使 用 可 信和 群 或 可 信用 户 (关于 钧 子 脚 本 的 相 
关 知 识 将 在 6.2 节 学 习 )。 我 们 在 hgrc 的 trusted WHY groups 中 添加 dev 群 。 如 果 该 文件 不 存在 ， 
则 直接 新 建 。 至 于 hgrc 的 路 径 ， 假 如 版 本 库 路 径 为 /varhg/testrepo/， 则 hgrc 位 于 /var/hg/ 
testrepo/.hg/hgre。clone 来 的 版 本 库 会 自动 生成 这 个 文件 ， 而 用 init 创建 的 版 本 库 并 不 会 自动 生 
成 ， 需 要 手动 创建 LIST 6.8 )。 





© LIST 6.8 在 hgrc 的 trusted THY groups 中 添加 dev 群 


[trusted] 


groups - dev 


6.1.4 使 用 设置 好 的 版 本 库 


如 果 想 通过 ssh 来 clone ee 需要 以 “ssh:// 主机 名 / 目录 ”的 形式 指 
定 clone 位 置 的 路 径 。 举 个 例子 ， 假 设 服务 融 可 通过 example.com 域名 进行 访问 ， 现 在 我 们 想 
clone 路 径 /var/hg/testrepo 下 的 版 本 库 ， 则 命令 e LIST 6.9 所 示 。 








Ej LIST 6.9 对 example.com 上 的 /var/hg/testrepo 版 本 库 执 行 clone 操作 


$ hg clone ssh://example.com//var/hg/testrepo 


指定 路 径 时 请 注意 和 料 杠 数 。 协 议 部 分 ssh://、 域 名 example.com 与 目录 /var/hg/ 
testrepo 的 结合 部 分 都 是 双 斜 杠 。 


NOTE 
通过 ssh 连接 时 如 果 需 要 密 钥 ， 就 需要 在 ssh 客户 端的 设置 文件 $HOME/.ssh/config 中 预 
先 设置 好 对 连接 对 象 使 用 的 密 钥 文件 。 


6.1.5 ”使 用 hgweb 建立 简易 中 央 版 本 库 


Mercurial 具有 hgweb 功能 ， 我 们 只 需 一 个 hg serve 命令 就 能 公开 版 本 库 浏 览 大 的 
Web 站 点 。 


$ hg serve 


启用 hgweb 功能 的 版 本 库 默 认 允 许 clone/pull, Æ hgrc 中 添加 设置 之 后 还 可 以 进行 push f 
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作 ， 所 以 对 于 一 些 仅 需 要 在 LAN 内 共 至 的 版 本 库 来 说 ， 启 用 hgweb 功能 后 就 可 以 当 作 中 央 版 
本 库 来 用 ， 能 省 去 不 少 功 夫 。 

我 们 在 “.hg/hgrc” 中 添加 以 下 设置 。allow push 是 允许 经 由 hgweb 进行 push 操作 的 user 
列表 ， 加 上 * 表示 不 需 认 证 即 可 push; push ssl 用 来 设置 push 时 是 否 需要 SSL, 





[web] 
allow push = * 


push _ ssl = False 
这 里 不 妨 加 上 -d 选项 ， 让 hgweb 的 Web Hos dei dES AILEAN hgweb 的 URL, 


$ hg serve -d 
listening ar tp oy 99g (oounad Eo =:8000) 


如 采 直 接 执行 hg clone 加 URL， 本 地 版 本 库 名 会 变 成 domain:port， 所 以 我 们 在 clone 时 添 
加 版 本 库 名 作为 第 二 传 值 参 数 。 


5$ hg elone mN/m ci eb 


如 下 所 示 ， 我 们 在 clone 来 的 版 本 库 中 进行 修改 ， 然 后 提交 并 push. 


5cedomonjucdoh 

o touch omongudob , xE 

$ hg cl -A -m "ace! monJjucdohn. tzr" 
adding monjudoh.txt 

“ae 

pushuangsetoshttps eor: 99909 
searching for changes 

remote: adding changesets 

remote: adding manifests 

remote: adding file changes 


remote: added 1 changesets with 1 changes to 1 files 


6.2 ”灵活 使 用 “钩子 


Mercurial ATIRE. MATIRE, Mts Mercurial 在 执行 特定 人 处理 时 还 能 够 额外 执行 
其 他 处 理 的 功能 ， 而 且 这 个 额外 处 理 是 任意 的 。 比 如 供 助 这 个 功能 ， 我 们 可 以 在 push 时 发 送 邮 
件 通知 ， 或 者 在 提交 之 前 目 动 检测 提交 是 否 有 芯 漏 等 。 

本 市 将 通过 几 个 实际 的 例子 ， 教 各 位 灵活 运用 Mercurial 的 钩子 功能 。 
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6.2.4 钩子 功能 的 设置 方法 


钩子 功能 的 设置 可 通过 在 hgrc 的 [hooks] 廊下 指定 shell 命令 或 Python 旺 数 来 进行 。 想 让 哪 
个 版 本 库 执行 钧 子 功 能 就 在 哪个 版 本 库 的 hgrc 中 进行 指定 。 比 如 在 6.2.2 节 ， 我 们 想 利 用 钩子 
功能 在 提交 时 检查 编码 风格 ， 那 么 就 在 本 地 版 本 库 的 hgrc 中 进行 指定 ; 又 比如 在 6.2.5 市 ， 我 们 
想 通过 钩子 功能 茶 止 中 央 厂 本 库 出 现 多 头 现象 ， 那 么 就 要 在 中 央 版 本 库 的 hgrc 中 进行 指定 。 





[hooks] 
commit — echo commit. 


update - python:myhook.sample 


如 打 在 一 个 钩子 事件 中 指定 了 多 个 钩子 脚本 ， 那 么 将 执行 最 后 一 个 。 





[hooks] 
update = python:myhook.sample1 
update = python:myhook.sample2 4 这 个 钓 子 事件 会 被 执行 
指定 为 空 时 不 会 执行 任何 操作 。 我 们 可 以 利用 空 指定 履 闭 已 有 操作 ， 从 而 避免 该 操作 被 
执行 。 








[hooks] 
update = python:myhook.sample1 
update = # update 钧 子 事 件 不 会 被 执行 


在 钩子 事件 名 后 面 加 上 后 缀 ， 就 能 让 同一 个 钩子 事件 执行 多 个 钩子 脚本 了 。 


[hooks] 
update.samplel = python:myhook.sample1 


update.sample2 - python:myhook.sample2 


6.2.2 Zinta TIZA 


如 今 网 络 上 有 许多 已 公开 的 钩子 脚本 ， 这 里 我 们 以 “提交 时 检验 PEPS 编码 风格 ”的 脚本 
为 例 进行 导入 。 该 脚本 包含 在 名 为 hbghooks 的 钩子 脚本 集 之 中 。 
这 个 hghooks 可 通过 pip 安装 。 








$ sudo pip install bghooks 


ERINA, HUE hooks 中 添加 以 下 设置 即 可 开始 使 用 。 





(D nttps://pypi.python.org/pypi/hghooks/ 


130 | 第 2 部 分 团队 开发 的 周期 


[hooks] 
pretxncommit.pep8 - python:hghooks.code.pep8hook 


6.2.3 ”钩子 事件 


钩子 事件 种 类 繁多 ， 下 面 我 们 对 应 命令 的 执行 类 型 ， 来 了 解 一 下 其 中 的 一 部 分 。 给 版 本 库 
设置 匆 子 功 能 时 ， 要 看 对 应 命令 是 否 会 给 版 本 库 带 来 变更 ， 这 两 种 情况 下 所 用 的 钧 子 事件 是 不 
一 样 的 。 

不 会 给 当前 操作 版 本 库 带 来 变更 的 命令 有 update、 从 当前 版 本 库 push、 被 其 他 版 本 库 pull 等 。 

会 给 当前 操作 版 本 库 带 来 变更 的 命令 有 commit、tag、 从 当前 版 本 库 pull、 被 其 他 版 本 库 
push 等 。 

接 下 来 ， 我 们 对 应 着 命令 来 了 解 一 些 已 定义 的 钩子 事件 。 其 中 ，changegroup 表示 changeset 
群 被 拿 到 版 本 库 时 的 事件 。 另 外 ， 对 changeset 群 中 各 个 changeset 执行 的 是 incoming. 




















€ update 时 
当前 操作 版 本 库 的 变更 集 不 会 被 变更 
(D preupdate 
(2) update 





@ 提交 时 
当前 操作 版 本 库 的 变更 集会 被 变更 


(D precommit 





(2) pretxncommit 


(3) commit 


€ 从 当前 版 本 库 push/ 被 其 他 版 本 库 pull 时 
器 其 他 版 本 库 发 送 变 更 集群 的 操作 。 当 前 操作 版 本 库 的 变更 集 不 会 被 变更 
D preoutgoing 








©) outgoing 


图 问 当前 版 本 库 pull 被 其 他 版 本 库 push 时 
接受 其 他 版 本 库 的 变更 集群 的 操作 。 当 前 操作 版 本 库 的 变更 集会 被 变更 
(D prechangegroup 








(2) pretxnchangegroup 
(3) changegroup 
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(4) incoming 
我 们 将 对 版 本 库 A 执行 各 操作 后 的 动作 汇总 成 了 下 表 。 


版 本 库 A 发 生 的 事件 版 本 库 B 发 生 的 事件 
preupdate, update 无 








hg commit precommit, pretxncommit, commit zB 





hg push B preoutgoing, outgoing prechangegroup, pretxnchangegroup, incoming 


hg pull B prechangegroup, pretxnchangegroup, incoming | preoutgoing, outgoing 














可 以 看 到 ， 对 于 部 分 会 给 当前 操作 版 本 库 变 更 集 带 来 变更 的 命令 ， 其 执行 时 发 生 的 事件 多 
WA pretxn 前 缀 。 这 是 因为 这 些 变更 是 事务 性 的 ， 钩 子 事件 必须 发 生 在 变更 处 理 已 结束 且 事 务 
尚未 确定 的 时 间 点 。 








6.2.4” 钓 子 功 能 的 执行 时 机 


接 下 来 详细 了 解 一 下 钩子 功能 。 

我 们 看 到 ， 版 本 库 发 生变 更 时 ， 有 些 钧 子 事件 币 有 pre 前 级 ， 有 些 却 没有 。 有 pre 前 级 的 多 
子 事件 位 于 执行 命令 指定 的 处 理 之 前 ,没有 前 级 的 则 位 于 执行 命令 指定 的 处 理 之 后 。pre 可 以 通 
过 exit 1 在 命令 指定 的 处 理 被 执行 之 前 了 直接 中 止 命令 。 

比如 我 们 把 /usr/bin/false 加 入 preupdate。 








[hooks] 
preupdate = echo preupdate;hg parents;/usr/bin/false; 
update - echo update;hg parents; 


如 下 所 示 ， 如 果 工 作 目 录 的 parent 处 于 tip (最 新 提交 ) 的 前 一 个 状态 ， 那 么 hg update tip 
命令 在 执行 时 将 被 preupdate 打 断 。 结 果 就 是 update 并 没有 执行 ， 工 作 目 录 的 parent 仍 保 持原 样 。 


$ hg log =-12 


changeset: 12:45648f583d32 

cage Cio 

user: monjudoh <monjudoh@gmail.com> 
date: Eras Dee 02 14303311 2011 +0900 
changeset: 11:2b1a3a2e66e29 

user: monjudoh «monjudohegmail.com- 
date: pru Dee 02 14302355 2011 +0900 


$ hg parents 
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changeset: 11:2b1a3a2e66e29 
user: monjudoh «monjudohGegmail.com-» 
date: Err Dec 02 14:02:55 2011 40900 


$ hg update tip 


preupdate 

changeset: LIL: 201834266629 

user: monjudoh «monjudohGegmail.com- 
date: Fri Dec 02 14:02:55 2011 +0900 


abort: preupdate hook exited with status 1 


$ hg parents 


changeset: LIL: 201838266629 
user: monjudoh «monjudohegmail.com- 
date: Fri Dec 02 14:02:55 2011 -«0900 


BUS EE AIEAEVURSE, TFA 3 种 : 有 pre 前 缀 的 、 有 pretxn 前 级 的 、 没 有 前 级 的 。pre 
位 于 命令 指定 的 处 理 被 执行 之 前 ，pretxn 位 于 处 理 实 际 执行 之 后 且 事 务 完成 之 前 ， 无 后 绥 的 位 
于 事务 完成 之 后 。 

比如 ， 我 们 这 里 设置 precommit、pretxncommit、commit 这 3 个 钧 子 事件 来 执行 hg tip。 
然后 执行 hg commit 会 发 现 ， 从 pretxncommit 起 tip SL SX EA T - 





[hooks] 

Precenmmiee enon en 

reeseonmmee eeneonselmeeonmne HenNoODE netu. 
eeommee eaneogeommee eNODE non 


$ hg ci -A -m "commit successful" 


precommit 

changeset: 28:8a68c4364175 

page tip 

user: monjudoh <monjudoh@gmail.com> 
date: Fri Dec 02 15:26:47 2011 +0900 


pretxncommit d3000a3cea812e687f2f6bac7aaa2716be003cab 


changeset: 29:d3000a3cea81 

tags tip 

user: monjudoh <monjudoh@gmail.com> 
date: Prl Dee 02 15:26:56 2011 +0900 


summary: commit successful 
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commit d3000a3cea812e687f2f6bac7aaa2716be003cab 


changeset: 29:d3000a3cea81 

tags tijo 

user: monjudoh <monjudoh@gmail.com> 
date: Bl Dee 02 15:26:58 2011 +0900 
summary : commit successful 


不 过 ， 由 于 pretxn 位 于 事务 完成 之 前 ， 所 以 在 pretxn 中 用 exit 1 可 以 实现 回 深 。 现 在 我 们 
把 /usr/bin/false 加 入 pretxncommit 中 试 试 看 。 


[hooks] 

precommit = echo pue commit ne ELp; 

pretxncommit = echo pretxncommit $HG NODE;hg tip;/usr/bin/false; 
eeomme enheogeomme enoDE tu 


$ hg parents 


changeset: 29:d3000a3cea81 

tags tip 

user: monjudoh <monjudoh@gmail.com> 
date: Srl Dee 02 15:26:58 2011 +0900 
summary: commit successful 


$ hg cel -m "commie taile” 


precommit 

changeset: 29:d3000a3cea81 

ice tip 

user: monjudoh <monjudoh@gmail.com> 
date: Frl Dee 02 15:26:58 2011 +0900 
summary : commit successful 


pretxncommit c42df85f2e7632b6e7ec124011b11ad8a9a3d61f 


changeset: 30:c42df£85f2e76 

itaq tip 

user: monjudoh <monjudoh@gmail.com> 
date: Erg Dee 02 15:36:52 2011 +0900 
summary : commit failed 


lramsagcutdenvdboti! 
rollback completed 


abort: pretxncommit hook exited with status 1 


$ hg parents 
changeset: 29:d3000a3cea81 
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ag: Eio 

user: monjudoh «monjudohegmail.com- 
date: Err Dec 02 15:26:58 2001] +0900 
summary: commit successful 


可 以 看 到 ，pretxncommit 时 反映 出 的 提交 已 经 被 撤销 。 灵 活 使 用 pretxncommit, pretxnchangegroup 
能 帮助 我 们 验证 提交 的 结果 或 push 的 结果 是 否 有 问题 ,并 且 在 有 问题 时 实现 回 深 。 











6.2.5 ”编写 钧 子 脚本 


€ 用 shell 脚本 实现 钓 子 脚本 
我 们 以 禁止 中 央 版 本 库 出 现 多 头 现象 的 钩子 脚本 为 例 , 来 了 解 一 下 用 shell 脚本 实现 的 钩子 
脚本 。 首 先 如 下 所 示 ， 将 脚本 放 到 任意 位 置 (“.hg” 之 下 就 不 错 )。 





#!/bin/bash 

# force-one-head 

# add the following to <repository>/.hg/hgrc : 
# [hooks] 


# pretxnchangegroup.forceonehead = /path/to/force-one-head 


if [ $(hg heads --template "{branch}\n"|sortļ|uniq|wc -1) != $(hg heads --temp 
late "[branch]WMn"|sort|wc -1) ]; then J 
echo "There are multiple heads." 
echo "Please 'hg pull' and get your repository up to date first." 
echo "Also, don't 'hg push --force' because that won't work either." 
exit 1 


£1 








接 下 来 ， 在 hgrc 中 将 其 指定 为 pretxnchangegroup 的 钧 子 脚 本 。 具 体 方法 如 下 。 


[hooks] 


pretxnchangegroup.forceonehead - .hg/force-one-head 


这 个 脚本 被 指定 给 了 pretxznchangegroup ， 所 以 它 的 执行 时 机 位 于 pusk 处 理 执行 之 后 且 事 务 
完成 之 前 。 因 此 我 们 可 以 在 push TUIS UM 了 各 种 Mercurial 命令 。 这 里 我 们 利用 heads 命 
邻 检查 是 否 出 现 多 头 现象 ， 如 果 出 现 则 通过 exit 1 回 滚 。 这 就 是 带 pretxn 前 级 的 钩子 事件 的 用 
法 之 一 。 











在 Mercurial 上 禁止 中 央 版 本 库 出 现 多 头 现象 
http://labs.timedia.co.jp/2011/09/reject-multiple-head.html 





© 用 Python 脚本 实现 钩子 脚本 
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这 里 我 们 讲 一 个 用 Python 脚本 实现 钧 子 脚 本 的 例子 ， 即 在 每 次 提交 时 都 对 第 2 草 中 完成 的 


留言 板 发 送 一 次 diff( LIST 6.10 )。 


© LIST 6.10 myhook.py 


= coding, uti-8 
import logging 


Ose We la 


# 接收 方 URL 


POST URLI- Mitte /L227 00 :868000 oe 


# 发 送信 息 的 格式 


MESSAGE FORMAT = """$(description)s 
a (elr) ewa 


det http Dost(url, cata): 
""" 用 POST 方法 向 url 发 送 data 


fp = urllib.urlopen (url, urllib.urlencode (data)) 


return fp.read() 


def postdiff(ui, repo, hooktype, node=None, 


"nnn 将 差别 用 HTTP 进行 POS EA £5 F PLZ 


# 获取 提交 的 上 下 文 对 象 


context = repo['tip!'] 


Source-None, **kwargs): 


# 从 上 下 文中 获取 差别 列表 ( 由 于 是 迭代 器 对 象 ， 所 以 要 列表 化 ) 


dret iist S aS (Context Aai E) 
# 将 差别 结合 成 文本 


Beste nip Peg c Eh q ee) 
# 获取 用 户 

user = context.user() 

# 获取 概要 


description = context .description () 


# 生成 要 发 送 的 信息 


message = MESSAGE FORMAT $ ['description': 


# 生成 发 送 数据 的 字典 
caes - 1 
'name!': user, 


Ecomment c emIessecdes 


description, ‘diffi: text diff} 
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# 发 送 
http post(POST URL, data) 
将 myhook.py 放 到 PYTHONPATH 的 影响 范围 之 下 ， 然 后 在 hgrc 中 作 如 下 描述 。 


[hooks] 
Gommliet = Dtnonmnooer .oar 


提交 后 ， 会 显示 如 图 6.1 所 示 的 结 


留言 记录 
Shinya Okano <tokibito@gmail.com> 的 留言 (2011712702 02:13:33): 





This is the commit message. 

diff -r 740f7 4a265 -r 6d3f37 4dObfc foo.txt 
——- fdev/null Thu Jan 01 00:00:00 1970 +0000 
+++ b/foo.t«t Fri Dec 02 02:13:33 2011 +0900 
Qe -00 +1,1 0 


+test 

diff -r ®740f?4a265 -r 6da f5 7 4dObfc test txt 
——- a/test.txt Fri Dec 02 01:41:32 2011 +0900 
+++ b/testtxt Fri Dec 02 02:13:33 2011 +0900 
Qo -1,3 +1,4 00 


6.1 向 留言 板 发 送 的 提交 信息 








用 Python 写 出 的 钩子 脚本 能 直接 使 用 context 对 象 。 当 输出 结果 需要 用 版 本 库 内 数据 进行 
条 件 判 断 等 加 工时 ，shell 脚本 不 但 要 人 处理 输出 格式 ， 还 必须 对 字符 串 进 行 操作 。 相 对 地 ， 
Python 脚本 只 需要 从 管理 各 修订 版 元 数据 的 context 对 象 中 获取 适当 信息 即 可 。 

另外 从 管理 方面 上 讲 ，Python 脚本 可 以 利用 Python 的 包 管 理 ， 用 pip 就 可 以 安装 ,十 分 
方便 。 





6.3 “分支 的 操作 





下 面 我 们 来 看 看 Mercurial 对 分 文 的 操作 。 所 谓 分 文 ， 是 指 厂 本 库 中 独立 存在 的 开发 线 。 分 
布 式 版 本 控制 系统 的 一 大 优势 就 在 于 各 个 本 地 环境 中 的 版 本 库 互 相 独 立 。 相 对 于 Subversion 等 
集中 式 版 本 控制 系统 ， 分 布 式 版 本 控制 系统 能 更 放心 地 处 理 分 文 。 





© LIST 6.11 hg branch 


$ hg brancin 
sepu 


lll LIST 6.11 所 示 ， 默 认 情 况 下 ， 版 本 库 中 只 存在 default 分 文 。 现 在 我 们 来 创建 一 个 新 分 
x (LIST 6.12 )。default 分 文 是 版 本 库 中 原本 就 存在 的 分 文 。 
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© LIST 6.12 hg branch ( 创建 分 支 ) 


$ hg branch test-branch 
$ hg branch 


test-branch 





分 支 创 建 出 来 之 后 ， 我 们 可 以 看 到 当前 分 支 变 成 了 test-branch。 不 过 对 Mercurial mr zi, 8 
建 分 支 的 流程 到 这 里 还 没有 结束 。 只 有 我 们 癌 新 分 支 做 过 提交 之 后 ， 这 个 分 支 才 会 具有 实体 。 
所 以 我 们 先 癌 分 支 中 添加 文件 ， 然 后 再 看 看 效果 ( LIST 6.13 )。 





NOTE 
Mercurial 允许 用 户 在 创建 分 支 后 直接 进行 提交 ， 不 必 添 加 或 删除 文件 。 


@ LIST 6.13 向 test-branch 添加 文件 以 及 提交 


$ Eouen teste: 
$ hg add test2.txt 
$ hg conmiLr 


至 此 分 支 创 建 完毕 ， 我 们 来 查看 所 有 分 支 (LIST 6.14 )。 





© LIST 6.14 hg branches ( 查看 所 有 分 支 ) 


$ hg branches 


test-branch  1:bcbc567db3add 
default 0:74471564b074 (inactive) 


不 出 意外 应 该 能 看 到 test-branch 和 default 两 个 分 支 。 接 下 来 我 们 回 到 default 分 支 。 


Ej LIST 6.15 hg update ( 分 支 间 的 切换 ) 


$ hg update default 





WH LIST 6.15 所 示 ， 用 hg update 能 在 分 文 间 进 行 切换 。 现 在 我 们 已 经 回 到 了 default 4) 3x. 
下 面 来 看 看 分 文 间 合并 的 相关 内 容 。 








6.4 关于 合并 


利用 Mercurial 等 版 本 控制 系统 进行 多 项 工作 时 ， 必 然 离 不 开 成 果 的 合并 。Mercurial 的 hg 
merge 命令 能 目 动 通过 三 路 合并 为 我 们 完成 合并 工作 ,但 并 不 是 说 所 有 人 情况 下 部 能 正常 合并 。 
本 市 ， 我 们 将 学 习 基 本 的 合并 流程 以 及 发 生 冲 突 时 的 应 对 方法 。 台 练 掌握 合并 的 相关 技巧 ， 能 
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让 各 位 对 版 本 控制 系统 更 加 得 心 应 手 。 


6.4.1 未 发 生 冲 突 的 合并 


多 和 名 成 员 并 行 开 发 时 会 发 生 多 头 现象 。 下 面 例子 中 就 存在 revl 和 rev2 两 个 头 。 要 解决 这 
问题 就 必须 进行 合并 。 








$ hg log -G --style compact 
© 2leip]s:® c0d244a079ce 2011-11-18 11:40 +0900 Geka 
| Cokibito 


|@ 1  ead8ad7a4d9f 2011-11-16 11:07 «0900 | monjudoh 


中 monjudoh 


o 0 fe75405e6383 29H 11:05 +0900 monjudoh 


ELESE COMMLE 


假设 现在 我 们 位 于 rev1， 进 行 合并 要 先 运 行 merge 命令 再 进行 提交 。 在 同一 分 文 内 合并 多 
头 时 ，merge 命令 不 a 





$ hg merge 
1 files updated, 0 files merged, 0 files removed, 0 files unresolved 
(branch merge, don't forget to commit) 


$ hg ci -m "merge" 
这 样 一 来 多 头 就 被 合并 成 了 一 个 头 。 
$ hg log -G --style compact 


@ 3 perol 2 2 [obe oale 2011=11=18 14:07 +0900 monjudoh 


\ merge 


© 230 c0d244a079ce 2011-11-18 11:40 +0900 iE o eulos zie, 
| tokibito 


1 ead8ad7a4d9f 2011-11-16 11:07 +0900 monjudoh 
7 monjudoh 


0 fe75405e6383 201L1L-11-16 11:05 +0900 monjudoh 


ELEGE COMMLE 


工作 中 我 们 也 经 常会 遇 到 合并 两 个 分 支 的 情况 。 下 面 的 例子 是 包含 default 和 tokibito ”两 个 


(D tokibito 为 本 章 撰写 者 风 野 真 也 先生 的 Twitter 用 户 名 。 一 一 编者 注 


分 文 的 状态 。 


S 


abort: 


hg log -G 
changeset: 
branch: 
caggi 
parent: 
user: 
date: 


summary: 


@ changeset: 


user: 
date: 


summary : 


changeset: 
user: 
date: 


summary: 
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2:a663elbf8f71 

tokibito 

i: 

0: £e75405e6383 

tokibito 

Pri Noy 16 11:40:13 2011 +0900 
tokit 


1:ead8ad7a4d9f 
monjudoh «monjudohegmail.com-» 
Wed Nov 16 11:07:59 2011 -«0900 


monjudoh 


0:fe75405e6383 
monjudoh «monjudohegmail.com- 
Wed Nov 16 11:05:34 2011 +0900 


ELESE tec e dne E 


此 时 就 不 能 用 无 传 值 参数 的 merge 命令 了 。 因 为 分 支 内 不 存在 多 头 ， 无 法 自动 选择 合并 
对 象 。 


hg merge 





branch 'default' has one head - please merge with an explicit rev 


(run 'hg heads' to see all heads) 


假设 我 们 位 于 default 分 文 的 rev1， 现 在 只 要 将 合并 对 象 的 分 文 名 交 给 merge fi WEB sc 





B 


$ hg merge tokibito 


1 files updated, 


(branch merge, 


0 files merged, 0 files removed, 0 files unresolved 


don't forget co Conme) 


$ hg ci -m "merge" 


: 
@ 


hg log -G 
changeset: 
Pa 


执行 后 的 合并 情况 如 下 。 我 们 是 在 default 分 文 下 指定 tokibito 475-3441 f. merge 命令 ， 所 
以 被 合并 的 那个 修订 版 现在 属于 default 分 支 。 这 里 干 万 注意 别 搞 错 合 并 方向 。 


| parent: 


3 3 visis On ee 
eLp 
1:ead8ad7a4d9f 
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| | parent: 2:a663e1bf8f71 

| | user: monjudoh «monjudohegmail.com-» 

| | date: Pri Nov 18 14:17:13 2011 0900 

| | summary: merge 

| | 

| o changeset: 2:a663e1bf8f71 

| | branch: tokibito 

| | parent: 0 : fe75405e6383 

I eer: tokibito 

| | date: HAL Nov 18 11:40:13 20121 +0900 

| | summary: bpoksbuto 

| | 

o | changeset: 1:ead8ad7a4d9f 

车 user: monjudoh «monjudohegmail.com-» 

| date: Wed Nov 16 11:07:59 2011 «0900 

| summary: monjudoh 

| 

o changeset: 0:fe75405e6383 
user: monjudoh «monjudohegmail.com- 
datek Wed Nov 16 11:05:34 2011 +0900 
summary : tu stocommst 


6.4.2 ”合并 时 发 生 冲 突 以 及 用 文本 编辑 器 解决 冲突 的 方法 
虽然 大 部 分 情况 下 合并 都 能 自动 完成 ， 然 而 一 旦 发 生 冲 突 ， 就 需要 我 们 来 手动 解决 问题 了 。 
假设 有 如 下 多 头 情 况 。 

$ hg log -G --style compact 


© Odffbb8f7780 2011-11-18 15:09 +0900 monjudoh 


other 


| 
| 
Inc aoGOReo ap 2011-11-16 15:068 +0900 monjudoh 
Iz ehis 

| 


o 0 0648c3b5afbd 2011-11-16 15:07 +0900 monjudoh 


base 





rev0, 1, 2 (base, this, other ) 中 conflict.txt 的 文件 内 容 分 别 如 下 所 示 。 


e revO ( base) 
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D 


e revi (this) 第 3 行 变 更 为 B 


pic 四 ur 


e rev2 ( other) 第 3 行 变 更 为 C 


DET w 


然后 我 们 在 revl (this) 执行 merge 命令 。 


E LIST 6.16 执行 合并 查看 冲突 


$ hg merge 

mergundgseonti-ctotxt 

merge: warning: conflicts during merge 

merging conflict.txt failed! 

0 files updated, 0 files merged, 0 files removed, 1 files unresolved 


use 'hg resolve' to retry unresolved file merges or 'hg update -C .' to abandon 


不 出 意外 应 该 会 看 到 如 LIST 6.16 所 示 的 消息 。 这 就 是 发 生 了 冲突 的 状态 ， 我 们 来 解决 它 。 
首先 执行 一 个 查看 冲突 状态 的 命令 。 
我 们 用 -1 选项 执行 hg resolve 命令 ， 发 现 conflict.txt 仍 处 于 未 解决 状态 ( LIST 6.17 )。 





Ej LIST 6.17 hg resolve -| ( 查看 冲突 ) 


$ hg resolve -1 
U ccomntiicb tot 


U 表示 “未 解决 ”( Unresolved )。 打 开 文 件 可 以 查看 冲突 的 位 置 ， 具 体 请 参考 “查看 冲突 位 
置 ” 部 分 的 内 容 。 这 里 与 其 他 版 本 控制 系统 一 样 ， 可 以 手动 进行 修正 。 











@ 查看 冲突 位 置 
我 们 打开 合并 时 发 生 冲 突 的 confliet.txt 文件 ， 会 发 现 内 容 变 成 了 下 面 的 样子 。 其 实 倘 单 说 
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来 ， 所 谓 发 生 冲 突 ， 避 ® 古 两 个 头 对 同一 个 文件 的 同一 行进 行 了 变更 ,计算 机 无 法 从 机 各 逻辑 层 
面 上 决定 采用 哪 一 方 。 要 解决 这 个 问题 ， 束 必须 由 人 类 明确 表示 出 采用 哪个 变更 。 





A 
A 


cececcc Tocat 


oos ober 
A 
A 


于 是 我 们 用 文本 编辑 硕 打 开 conflict.txt， 手 动 编辑 出 合并 后 的 confliet.txt 文件 。 这 里 我 们 采 
用 revl (this ) 的 变更 。 


D P WÙ P N 


Mercurial 当然 不 知道 人 类 是 否 解 决 了 冲突 ， 所 以 现在 执行 hg resolve -1 仍然 会 出 现 之 
前 的 结果 。 此 时 我 们 要 用 hg resolve -m 将 当前 状态 从 “冲突 未 解决 ”设置 为 “冲突 解决 完 
毕 ”( LIST 6.18 )。 然 后 只 要 提交 即 可 。 


© LIST 6.18 hg resolve -m ( 解决 冲突 ) 


hg resolve -m conflict.txt 
hg resolve -I 
omisit 


hg ci -m "merge" 


3 [etp] 1,2 72367726805 20LL-LL-18 16:08 +0900 monjudoh 


\ merge 


| 
© 220 Ocltflbet7790 2011-11-18 15:09 40900 monjudoh 
| other 

| 

| 


5 

5 

R 

S 

$ hg log -G --style compact 
@ 

| 

| 

| 

| 

| 

O 1 a239fe812ab0 2011-11-18 15:08 40900 monjudoh 
lr this 

| 

© 0 0648c3b5afbd 2011-11-18 15:07 +0900 monjudoh 


base 
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6.4.3 合 井 的 尖 孚 与 冲突 


上 面 我 们 提 到 冲突 是 “计算 机 无 法 从 机 融 逻 辑 层 面 上 决定 采用 哪 一 方 ”的 状态 ， 这 里 将 对 
此 作 进 一 步 的 说 明 。 
这 里 依然 和 前 面 一 样 ， 假 设 出 现 了 如 下 多 头 现象 。 


$ hg log -G --style compact 

© 2ltip]:0 Odffbb8f7780 2011-11-18 15:09 40900 monjudoh 
| other 

| 

BON! a239fe812ab0 201L1L-11-16 15:08 +0900 monjudoh 

ul this 

| 

© 0 0648c3b5afbd IO le 15307 +0900 monjudoh 


base 


rev0 ( base ) 的 conflict.txt 文件 的 内 容 如 下 。 


poop 





我 们 将 revl, 2 (this, other) 对 第 3 行 的 修改 情况 以 及 合并 后 的 结果 总 结 成 了 下 表 (合并 





B ( XH this 的 变更 ) 
C ( 采用 other 的 变更 ) 
B ( 碰巧 合并 成 功 ) 


冲突 




















~ (部 是 合并 成 功 。 册 的 双方 都 没有 作 变 更 ， 所 以 合并 结果 中 也 没有 出 现 变 更 。 

和 (3) 都 只 有 一 方 作 了 变更 ， 所 以 只 采用 变更 的 一 方 。 

出 比较 特殊 ， 虽 然 双 方 都 对 同一 行 作 了 变更 ， 但 变更 内 容 是 相同 的 ， 所 以 可 以 直接 采用 。 
具体 全 的 情况 下 能 不 能 成 功 合并 还 要 看 版 本 控制 系统 的 种 类 ， 虽 然 Mercurial 认为 是 成 功 ， 但 有 
一 部 分 版 本 控制 系统 会 判定 为 冲突 。 
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( 引 ) 是 双方 对 同一 行 作 了 不 同 变 更 ， 于 是 出 现 了 冲突 。 


6.44 ”用 GUI 的 合并 工具 进行 合并 
除 命令 行 之 外 ，Mercurial 还 支持 用 GUI 的 合并 工具 进行 合并 。 


e KDiff3 
这 里 以 KDiff31 为 例 介 绍 GUI 的 合并 工具 。KDiff3 支持 OS X. Windows. Linux, HIDE 
行 三 路 合并 ， 是 GPLv2 的 OSS., 


e 安装 KDiff3 
任何 环境 下 都 能 轻松 安装 KDiff3 。 


O 在 OSX 上 安装 

下 载 dmg 并 解压 ， 将 解压 出 来 的 kdiff3.app 放 到 应 用 程序 文件 夹 中 。OS X10.9 无 法 直接 使 
用 放 在 文件 夹 中 的 kdiff3.app。 初 次 双击 启动 kdiff3.app 时 ， 系 统 会 弹出 对 话 框 通知 无 法 启动 
(图 6.2 ). 

















打 不 开 “kdiff3”， 因 为 它 来 自身 份 不 明 的 开发 
者 。 

| ^Al 您 的 安全 性 偏好 设置 仅 允许 安装 来 自 Mac App Store 和 被 
认可 开发 者 的 应 用 。 


“kdiff3” 位 于 磁盘 映像 "kdiff3-0.9,98- 
MacOSX-64Bit.dmg", "Google Chrome” FREK 23:52 


下 载 了 此 磁盘 映像 。 
we 





6.2 ”通知 kdiff3.app 无 法 启动 的 对 话 框 


于 是 我 们 需要 以 下 流程 。 
初次 局 动 时 不 要 双击 ， 要 点 右键 通过 上 下 文 沫 单打 开 〈 图 6.3 )。 


Oe i kdiff3 











图 6.3 ”通过 上 下 文 菜单 打开 
此 时 会 弹出 确认 局 动 的 对 话 杠 ,点击 “ 打 开 ” 便 能 局 动 kdifG.app (d 6.4 )。 只 要 第 一 次 成 


(D http://kdiff3.sourceforge.net/ 
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功 局 动 ， 以 后 我 们 就 可 以 通过 双击 打开 它 了 。 


“kdiff3 来 自身 份 不 明 的 开发 者 。 您 确定 要 打开 


X. 它 吗 ? 
ig" 打开 “kdiff3” 将 始终 允许 它 在 这 台 Mac 上 运行。 


“kdiff3” 位 于 磁盘 映像 “kdiff3-0.9.98- 
MacOSX-64Bit.dmg”。“Google Chrome” 于 昨天 23:52 
下 载 了 此 磁盘 映像 。 





6.4 ”确认 启动 的 对 话 框 


O 在 Windows 上 安装 
下 载 安 装 包 并 运行 。 








O Æ Linux ( 基于 Debian ) 上 安装 


$ sudo apt-get install kdiff3 


O 在 hgrc 中 设置 merge-tools 
要 想 关 联 KDiff3， 在 合并 发 生 冲 突 时 通过 它 来 解决 问题 ， 需 要 在 hgrc 或 Mercurial.ini 
( Windows 的 情况 下 ) 中 作 以 下 设置 。 


[merge-patterns] 

SSE S KALEEI 

[merge-tools] 

# Override stock tool location 
# MacOSX 

kdiff3.executable = /Applications/kdiff3.app/Contents/MacOS/kdiff3 
Windows 
kdiff3.regkey-SoftwareNKDiff3 
kdiff3.regappend-Nkdiff3.exe 
kdiff3.fixeol=True 

lcdabtbo gun-Irue 

biimu 


kdiff3.executable - -/bin/kdiff3 


+ + Gb Gb Gb # d 


4 Specify command line 

kdiff3.args = $base $1ocal $other -o $output 

# Windows 

# kdiff3.args---auto --L1 base --L2 local --L3 other $base $1ocal S$other -o $output 
# Give higher priority 

keir priority = 1 
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在 merge-tools 市 的 kdiff3 中 设置 KDiff3 的 命令 以 及 命令 行 对 象 ， 然 后 在 merge-patterns 市 
中 设置 所 有 文件 冲突 都 使 用 kdiff3 解决 。 


O 用 KDiff3 解决 冲突 
我 们 还 以 6.4.2 节 描 述 的 状态 为 例 ， 给 版 本 库 执行 hg merge 命令 。 随 后 conflict.txt 发 生 冲 
突 ，KDiff3 自动 启动 (图 6.5 )。 





è E &à m 三 三 a v 2 v» £t X A B c » 





A(Base) ct.txt-base.2wvXwO m" B: pos/mado/conflict.txt.orig m" C: »-/conflict.txt-other.tEEilh | ... 
Top line 1 Encoding: Sy:Line end style Top line 1 Encoding: Sy:Line end style Top line 1 Encoding: Sy:Line end styli 
A A A 





A A A 
mi: mI RI: 
A Ls A A A 


Encoding for saving:| Codec from C: System Line end style:! Unix (A, B, C) 








A 
? ][94erge Conflict» 
A 








| Number of remaining unsolved conflicts: 1 (of which 0 are whitespace) Z 
————— o ———— ——— —À' 


65 因 发 生 冲 突 而 启动 KDiff3 之 后 的 状态 


左 、 中 、 右 的 A、B、C 中 分 别 是 多 头 共同 的 祖先 版 本 、 执 行 merge 命令 时 的 parent 修订 
版 、 执 行 merge 命令 时 的 男 一 个 最 新 修订 版 中 的 conflict.txt 内 容 ， 下 方 的 视图 显示 了 合并 完成 
后 的 结 来 。 我 们 可 以 看 到 发 生 冲 突 的 地 方 显示 为 红色 。 前 面 也 说 了 ,解决 冲突 就 是 要 在 发 生 冲 
突 的 位 置 明确 选择 采用 (或 者 不 采用 ) 某 一 方 的 变更 。 

在 KDiff3 中 ， 右 键 点 击发 生 冲 突 的 位 置 ， 就 会 显示 菜单 供 我 们 选择 变更 ( 图 6.6 )。 




















Output: onflict.txt Encoding for savin 
ls. 
2jete— ———- 
A A Select Line(s) From A 381 


E Select Line(s) From B %2 


€ Select Line(s) From C #3 


6.6 KDiff3 解决 冲突 时 选择 变更 的 菜单 


这 里 我 们 选 B( 图 6.7 )。 
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A (Base): ct.txt-base.2wvXwO | ... | B: pos/mado/conflict.txt.orig mee C: 5-/conflict.txt~other.tEEilh -—| 
Top line 1 Encoding: Sy:Line end style Top line 1 Encoding: Sy:Line e 
A A 


nd style Top line 1 Encoding: Sy:Line end styl: 
A A A 
m^ LIES Eic 

A e A ^ A 





Output: onflict.txt Encoding for saving:| Codec from C: System — |$ ]Line end s 
] A 
A 


5] 


IE 





图 6.7 KDiff3 选择 采用 B 时 的 状态 








现在 的 状态 是 冲突 已 解决 ,界面 中 也 明确 显示 出 了 合并 对 和 象 的 行 采 用 了 哪 一 个 结果 。 随 后 
保存 文件 并 退出 即 可 。 


$ hg merge 
merdgang Coar LLGC o TXE 


0 files updated, 1 files merged 


(branch merge, 


, 0 files removed, O files unresolved 


conde Onge ORCO) 





XH] KDiff3 的 同时 merge 命令 也 就 执行 与 未 设置 合并 工具 的 合并 不 同 ， 这 里 没有 
出 现 Unresolved 的 文件 。 最 后 只 要 提交 一 下 ， = 并 工作 就 完工 了 。 





65 GUI 客户 端 





在 前 面 的 说 明 中 ， 我 们 一 直 在 使 用 Mercurial 的 命令 工具 (CUI 客 户 端 )， 其 实 Mercurial 也 
有 GUI 客户 端 工具 的 。 本 节 我 们 将 了 解 一 下 GUI 客户 端的 优 缺 点 ， 以 及 一 些 工 具 。 
6.5.1 GUI 客户 端的 介绍 
这 里 先 介绍 一 些 主要 的 GUI 客户 端 及 其 导 人 方法 。 
€. TortoiseHg 


TortoiseHg "最 早 是 Windows 专用 的 GUI 客户 端 ， 如 今 已 经 可 以 在 Windows/OS X/Linux 上 
路 平台 使 用 了 (网 6.8 )。 


(D nttp://tortoisehg.bitbucket.org/ 
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ee æ foo clone3 - TortoiseHg T fF& 








日 修订 集 : 1 (88fl9accd84b) this 
用 户 :  monjudoh «monjudoh example@gmail.com> 
日 期 : 2016-09-04 13:54:38 «0800 (5 分 钟 前 ) 
父 版 本 : 924279328b9fd) base 








d B o4 $ $ 3 | 总 conmictbd 


69 -1,5 «1,5 ee 
A 











一 


6.8 TortoiseHg 的 示例 界面 


O 安装 
在 OS X 环境 下 ， 要 通过 Phttp:// 人 tortoisehg.bitbucket .org/download/index. 
html — zip 格式 的 app 压缩 包 ， 解 压 后 将 TortoiseHg.app 放 到 应 用 程序 文件 夹 中 并 
。 之 后 的 流程 与 安装 KDiff3 时 一 样 。 在 Windows 环境 下 ， 只 要 从 http://tortoisehg. 
bitbucket .org/ 下 载 安 装 包 直接 运行 安装 即 可 。 如 果 是 Linux, http://tortoisehg. 


bitbucket. a index.html 也 写 了 哪个 发 布 版 有 程序 包 可 用 。 如 果 各 位 的 环 
境 有 相应 程序 包 ， 可 以 通过 apt 等 包 管 理 系统 进行 安装 




















€ SourceTree 


SourceTree" 是 Atlassian 提供 的 商用 GUI 客户 端 ， 同 时 支持 Mercurial 和 Git。 最 早 是 OS X 
专用 的 GUI 客户 端 ， 现 在 则 可 以 同时 支持 OS X 和 Windows( 图 6.9 )。 


ece example (Mercurial) 
O OOQ bh i GE o 
提交 拉 取 "x 9* 85 nm 在 Finder 中 显示 Hw 设置 
LL] work 所 有 分 支 RN: -- D 

文件 状态 nt HI. 作者 日 期 

Qip [rdefautt other 2 monjudoh «monju.. 今天 13:54 

pn [9 oL ONNNNNNENENLICCIILDS CI | 

搜索 ba 0 monjudoh «monjud.. SR 13:51 
b ex 
O defaul 

default : 

PANUSGHIR ~ =E * 
内 conflict.txt 
Q» sa 
f [RE S 

C» an 

default 
Bus 

修订 版 本 : 1 

B es 变更 集 : 88f19accd84bf589232c262f7dfafa4a65be3993 [... 


父 级 : 0 
作者 : ”monjudoh «monjudoh example@gmail.com> 
日 期 : ”2016 年 9 月 4 日 GMT+8 13:54:38 








O 
6.9 SourceTree 的 示例 界面 


(D http://www.sourcetreeapp.com/ 
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H 


OTa 
如 果 是 OS X 环境 ， 需 要 从 http://www.sourcetreeapp .com/ FE dmg 文件 ， 然 后 
将 解压 出 来 的 SourceTree.app 放 入 应 用 程序 文件 夹 并 安装 。Mac App Store 上 只 提供 了 旧版 本 ， 
所 以 请 不 要 用 那个 。 如 果 是 Windows 环境 ， 则 要 从 nttp://www.sourcetreeapp.com/ F 
due). EBERT o 
至 于 合并 工具 的 设置 ， 在 “环境 设置 ”一 “Diff ”的 “外 部 代码 差异 对 比 / 合 并 ”部 分 进 
行 ( 图 6.10 )。 


^j 





























e Diff 
mmHg 993596260 
通用 Diff “提交 模板 Mercurial Git BENAF ”网络 EM 
内 建 Diff 查 看 器 
比 对 视图 字体 : 1 lar 10.0 p 变更 
pif: | 3 (2 NEN NEN E 
大 小 限制 (文本 ) 1,024 KB ”大 小 限制 (二 进 制 ) 10,240 KB 
忽略 文件 模式 : — * pbxuser, *xcuserstate 
外 部 代码 差异 对 比 /合并 
可 视 对 比 工具 :  KDiff3 
比较 命令 : 参数 : 
合并 工具 kit 
合并 命令 : 参数 : 
“其 他 "可 以 使 用 的 命令 行 参数 : SLOCAL (= 我 的 ) SREMOTE (= 你 的 ), SBASE (= 同 源 的 ), SMERGED (= 合并 输出 的 ) 








6.10 设置 SourceTree 的 合并 工具 


6.5.2 GUI 客户 端的 优点 
下 面 我 们 以 TortoiseHg 为 例 来 看 看 GUI KF mR 


@ 显示 历史 图 

GUI 客户 闪 最 大 的 特点 怠 是 时 稼 显示 历史 岁 ， 并 且 能 以 它 为 起 点 进行 多 种 操作 。 

如 图 6.11 所 示 ， 打 开工 作 台 ， 上 部 和 窗 格 显示 历史 图 ， 左 下 窗 格 显 示 历 史 图 中 已 选 定 的 修订 
版 与 其 parent 之 间 的 status， 右 下 的 窗 格 则 显示 提交 日 志 以 及 status 窗 格 中 已 选 定 文件 的 diff。 
在 历史 图 上 右键 点 击 各 修订 版 可 以 直接 执行 update 等 操作 ， 十 分 方便 。 
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ece æ example - TortoiseHg T fF& 
[ Q 


i e i t 
i 7 ie i i E d 
mer Win 2x 作者 时 间 标签 。 开发 阶段 ”描述 
O 0+ default monjudoh 现在 THHendisX! * IÍFER* 
CE tnis 


default monjudoh 8 分 钟 前 tip — secret 
default monjudoh 9 分 钟 前 secret — base 



































日 修订 集 : 1 (90feb0005833) this 
用 户 :  monjudoh «monjudoh example gmail.com» 
日 期 : 2016-09-04 14:25:21 «0800 (8 分 钟 前 ) 
父 版 本 : 9_C8f4db46fell) base 
标签 : tip 
his 








iii BOW o a&i [Bontot 
1,5 «1,5 ee 








T 


6.11  TortoiseHg 的 工作 台 


€ 工作 目录 的 状态 与 差别 的 显示 











在 历史 图 中 ， 工 作 目 录 与 修订 版 尘 受 同等 待遇 。 选 择 工 作 目 录 后 ， 左 下 窗 格 显示 status, 








下 窗 格 显示 提交 日 志 的 草稿 以 及 diff( 图 6.12 )。 


» example - TortoiseHg 工作 台 


le. ` «d 
Lr Du: no 1 —- EL] [zi 开发 阶段 m 
judoh 现在 


zd 9 分 支 : default 。 复员 提交 说 明 ax EJ 
父 版 本 : 9 Caftabtefella) base 


不 是 Head 版 本 ! 
other 





cm 


$ 8 za 3 o f conflictxt 








图 6.12 TortoiseHg 的 工作 台 ( 选择 了 工作 目录 的 状态 ) 


右 


NNNM RED ER. V HMM 


面 的 失误 ， 比 如 出 现 了 不 该 有 的 变更 ， 或 者 在 没有 进行 add/remove 的 情况 下 就 进行 


@ 合并 


O TortoiseHg 
TortoiseHg 会 在 合并 发 生 冲 突 时 显示 Unresolved 文件 的 列表 。 
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ece A 解决 冲突 - example 
O 有 需要 解决 的 合并 冲突 
本 地 修订 版 本 信息 并 入 修订 版 本 信息 
修订 版 本 : 1 (fac4e279dfc7) 修订 版 本 : 2 (151bd460d707) 
摘要 : other 
用 户 : monjudoh «monjudoh example gmail.com> RP: monjudoh «monjudoh example gmail.com» 
日 期 : 2016-09-04 14:59:56 +0800 (3 分 钟 前 ) 日 期 : 2016-09-04 15:00:18 +0800 (3 分 钟 前 ) 
分 支 ; default 
标签 : tip 


未 解决 的 冲突 





工具 解决 (R) 

采用 本 地 (T) 

采用 其 他 (O) 
标 为 已 解决 (M) 











编辑 文件 (E) 
可 视 化 三 路 合并 (W) 


iff to Other 


标记 为 未 解决 (U) 
检测 合并 /差异 工具 : R B 


命令 输出 








6.13 TortoiseHg 解决 冲突 的 界面 


如 图 6.13 所 示 ， 我 们 可 以 选择 Unresolved 的 文件 并 点 击 右键 ， 并 从 下 述 解 决 方案 中 进行 
选择 。 
e 通过 Mercurial 消除 冲突 
e 通常 我 们 在 合并 时 都 选择 了 “尽量 自动 消除 合并 冲突 "， 所 以 不 选用 这 个 
启动 GUI 客户 病 消 除 冲突 
采用 当前 所 处 位 置 的 最 新 版 本 ， 并 将 状态 改 为 Resolved 
e 采用 合并 目标 一 方 的 最 新 版 本 ， 并 将 状态 改 为 Resolved 
e 编辑 Unresolved 文件 后 将 状态 改 为 Resolved 








6.5.3 GUI 客户 端的 缺点 
GUI 客户 端的 缺点 如 下 。 


。 操作 对 象 必须 是 PC 本 地 版 本 库 。 通 过 ssh 在 服务 保 上 工作 时 无 法 使 用 它们 
e hg 命令 只 要 导入 extension 就 能 轻松 地 添加 功能 ， 但 GUI 客户 端 只 能 使 用 其 固定 文 持 的 


extension 





LULA Ud, HJLSEPPR GUI 2€ P 9mgsbte Bt TFIA terminal 的 功能 ， 在 用 户 觉得 
用 CUI 更 好 的 时 候 能 随时 切换 到 CUI。 至 于 在 服务 天 上 工作 的 问题 ， 我 们 平时 的 提交 可 以 通 


过 CUI 进行 ， 遇 到 合并 等 用 GUI 更 方便 的 操作 时 ， 可 以 先 把 版 本 库 pull 到 本 地 再 用 GUI 客户 
端 处 理 。 
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66 ”考虑 实际 运用 的 BePROUD Mercurial Workflow 





多 人 合作 进行 开发 时 ， 难免 会 直到 几 个 本 地 环境 之 间 的 提交 出 现 予 盾 ， 以 及 为 解决 矛盾 需 
要 进行 合并 的 情况 。 为 外 ， 在 多 种 功能 同时 进行 开发 的 过 程 中 ,很 可 能 后 实现 的 功能 需要 和 完 发 
布 。 为 防止 这 类 情况 给 团队 开发 市 来 混乱 ， 保 证 开发 和 发 布 的 顺利 进行 ， 我 们 必须 事先 确定 好 
版 本 库 创建 分 支 与 合并 分 支 的 时 机 。 

为 外 ， 我 们 的 理想 情况 是 所 有 工作 人 员 痢 可 以 通过 命令 行 对 版 本 库 进行 操作 ,但 有 些 时 候 
条 件 所 限 并 不 能 满足 这 一 要 求 。 为 在 这 种 情况 下 也 能 保证 工作 进度 ， 我 们 需要 用 到 一 些 工具 ， 
些 工 具 也 会 在 本 部 分 进行 介绍 。 

















A 
^ 
6.6.1 概述 


这 里 将 介绍 的 是 我 们 自己 使 用 Mercurial 进行 源码 管理 的 工作 流程 和 管理 结构 。 我 们 将 在 讲 
述 项 目 相 关 人 员 以 及 开发 方法 等 背景 的 基础 上 ， 为 各 位 说 明 工 作 流 程 的 相关 内 容 。 





NOTE 
本 节 内 容 以 bpmercurial-workflow 文档 为 基础 。 文 档 与 源码 的 许可 证 为 CC BY 2.1。 本 节 
讲述 的 流程 与 Web 版 相同 ， 只 是 为 了 方便 阅读 对 结构 和 文章 作 了 少量 修改 。 
bpmercurial-workflow 文档 
http://beproud.bitbucket.org/bpmercurial-workflow/]ja/ 


CC BY 2.1 


https://creativecommons.org/licenses/by/2.1/au/ 


662 ”背景 





既然 要 说 明 工 作 流 程 ， 那 日 然 少不了 项 目的 背景 。 所 以 我 们 先 来 了 解 一 下 背景 。 


@ 目标 项 目 
在 这 个 工作 流程 中 我 们 的 目标 项 目 是 开发 应 用 于 B to C 的 Web 站 点 (包括 系统 在 内 )。 
多 个 小 开发 任务 (包括 设计 变更 等 ) 并 行进 行 ， 支持 发 布 顺 序 不 定 的 情况 。 





(D Creative Commons， 简 称 CC， 中 国 大 陆 正 式 名 称 为 知识 共享 ， 是 一 个 非 营 利 组 织 ， 也 是 一 种 创作 的 授 
权 方 式 。 此 组 织 的 主要 宗旨 在 于 增加 创意 作品 的 流通 可 及 性 ， 作 为 其 他 人 据 以 创作 及 共享 的 基础 ， 并 
寻找 适当 的 法 律 以 确保 上 述 理念 。 一 一 编者 注 
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源码 等 成 品 的 交付 工作 ， 均 通过 Mercurial 向 客户 管理 的 版 本 库 ( 后 述 的 发 布 版 本 库 ) 进 
fT push. 
€ 这 个 工作 流程 的 相关 人 员 
O 程序 员 
提交 系统 的 源码 ， 主 要 负责 管理 版 本 库 的 人 员 。 分 文 的 合并 与 切换 也 由 程序 员 人 负责 。 
服务 硕 上 已 经 为 成 员 准 备 了 各 目的 用 户 账户 。 为 方便 说 明 ， 我 们 这 里 假设 程序 员 的 用 户 儿 


为 programmer。 





O 设计 师 
提交 HTML 模板 、 各 种 媒体 文件 的 人 员 。 也 可 能 是 网 页 制作 工程 师 。 
设计 师 需 要 向 服务 右上 传 文 件 ， 所 以 也 备 有 用 户 账 户 。 








O 客户 
接受 开发 完成 的 源码 等 成 品 的 人 员 。 通 过 后 述 的 发 布 版 本 库 取 走 源 人 三。 





e 工作 环境 

程序 员 和 设计 师 对 源码 进行 修改 、 测 试 等 工作 的 环境 ， 即 服务 器 或 本 地 机 器 上 的 环境 。 

本 书 中 ， 我 们 将 在 给 开发 专 设 的 服务 器 (Linux ) 上 对 版 本 库 进 行 操 作 。 至 于 设计 师 工 作 的 
服务 器 环境 ， 我 们 也 已 经 保证 该 环境 能 启动 应 用 程序 服务 需 来 查看 模板 文件 等 是 否 正常 工作 。 
以 Python/Django 为 例 来 说 ， 就 是 用 runserver 等 来 负责 局 动 。 














6.6.3 ”版 本 库 的 结构 


我 们 使 用 的 是 分 布 式 版 本 控制 系统 ， 所 以 必须 掌握 版 本 库 的 结构 以 及 各 版 本 库 的 作用 
(图 6.14 )。 


ug — EN — ug 
 . ———————— 才 ——————— 


release master working 


图 6.14 版 本 库 的 结构 


€ 主 版 本 库 ( master ) 

包含 所 有 成 果 的 版 本 库 。 用 来 积累 以 及 共 至 整个 团队 每 天 开发 出 来 的 成 有 果 ( 比如 开发 中 的 
4] 3C Ja 

版 本 库 路 径 示 例 : /var/hg/example-prj 
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€ 发布 版 本 库 ( release ) 
疾 有 已 完成 开发 日 等 待 发布 到 生产 环境 中 的 源码 。 放 入 这 个 版 本 库 中 的 代码 就 是 我 们 交 给 客户 
的 成 品 。 客 户 会 使 用 这 个 版 本 库 中 的 代码 进行 部 署 等 工作 。 一 般 只 有 default 分 文 处 于 活动 状态 。 
进行 发 布 ( 交付 ) 工作 时 ， 我 们 要 把 default 分 支 从 主 版 本 库 push. 到 发 布 版 本 库 。 
版 本 库 路 径 示 例 : /var/hg/example-prj-release 





图 工作 版 本 库 ( working ) 

进行 源码 添加 及 修改 等 工作 的 版 本 库 。 开 发 成 有 末 要 多 提 交 到 这 个 版 本 库 ， 然 后 于 push 到 主 
版 本 库 。 获 取 其 他 人 的 开发 成 采 时 ， 要 从 主 版 本 库 pull 到 这 个 版 本 库 。 

工作 版 本 库 既 可 以 在 服务 硕 上 也 可 以 在 本 地 环境 上 。 


由 于 本 书 所 介绍 的 开发 将 在 服务 各 上 进行 ， 所 以 我 们 将 主 版 本 库 clone 至 工作 人 员 在 服务 天 
EDERT P. 


版 本 库 路 径 示 例 : /home/programmer/example-prj o 





6.6.4 ”提交 源码 


源码 写 好 后 要 提交 到 工作 版 本 库 。 
default 分 文 要 时 第 用 于 发 布 ， 所 以 在 提交 成 果 时 ， 除 了 为 发 布 而 进行 合并 以 外 部 要 使 用 其 














e 问题 与 分 支 

我 们 在 第 5 章 中 也 提 到 了 ， 修 改 源码 时 要 先 发 起 问题 ， 然 后 根据 问题 编号 创建 相应 分 文 。 
O 示例 

为 了 修改 源码 ， 我 们 在 问题 跟踪 系统 中 创建 了 编号 为 #5 的 问题 ( 图 6.15 )。 





问题 II MEL NE NES D: wiki Xx# EE 


功能 #5 

开发 个 人 主页 功能 

& tokibito 在 3 分 钟 之 前 添加 . 更 新 于 3 分 钟 之 前 
状态 : 新 建 开始 日 期 : 
优先 级 : Hä 计划 完成 日 期 : 
指派 给 : tokibito % 完成 : 
yl: - 耗 时 : 
目标 版 本 : alphai 

描述 

开发 登录 后 才 可 以 使 用 的 个 人 主页 功能 。 








图 6.15 ”在 问题 跟踪 系统 中 创建 的 问题 
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这 种 情况 下 ， 修 改 后 的 源码 要 提交 到 t5 分 文 。 于 是 我 们 新 建 t5 分 文 。 


$ CQ ~ 

$ cd example-prj 

$ hg branch d 查看 当前 分 支 

demenis 

s # 问题 编号 为 5， 所 以 从 default 分 支 创建 名 为 t5 的 分 支 


$ hg branch t5 
接 下 来 ， 将 源码 添加 成 为 管理 对 象 ， 然 后 提交 。 


$ hg aad 
S hg conme 


这 样 就 可 以 将 我 们 的 修改 提交 上 去 了 。 
在 这 个 状态 下 ，default 分 文 并 没有 被 修改 ， 所 以 就 算 其 中 的 代码 传 到 其 他 版本 库 〈 比 如 发 
布 版 本 库 等 )， 我 们 所 作 的 修改 也 不 会 被 发 布 ( 图 6.16 )。 


O Ate» Q .lh-uimu^tp t5. 








历史 图 修订 版 ”分支 作者 时 间 标签 ”开发 阶 息 ”描述 
O 4+ t5 Shinya Okano 现在 * 工作 目录 交 
©) 4 t5 Shinya Okano 3 分 钟 前 tip draft t5|tp E E:$ AE Ay 
3 t3 Shinya Okano 5 分 钟 前 draft (3 #3 制作 管理 界面 
2 t2 Shinya Okano 7 分 钟 前 draft (2 4s2'8Etin 
1 ti Shinya Okano 9 分 钟 前 draft 计 #1 开发 登录 功能 
0 default Shinya Okano 2 小 时 前 draft default init repo 





6.16 向 分 支 提 交 之 后 的 历史 图 


一 般 阅 来 ， 修 改过 的 源码 不 会 很 快 被 发 布 。 
如 果 我 们 将 暂 不 发 布 的 源码 提交 到 了 default 分 文 ， 那 么 一 旦 遇 到 需要 插入 临时 发 布 的 情 
就 必需 面临 很 多 容易 出 问题 的 操作 ， 比 如 多 尖 现 象 、 删 除 不 合适 的 变更 等 。 
只 有 到 了 发 布 那 一 刻 才能 将 源码 提交 至 default 分 支 ， 也 就 是 在 开发 过 程 中 保证 源码 只 出 现 
在 开发 分 文 里 ， 这 样 才能 保证 安全 。 

我 们 将 工作 版 本 库 的 更 改 传 到 主 版 本 库 ， 有 具体 代码 如 下 。 











i 


3 


$ hg push --new-branch R j&XE nev branch nie NN 


hg push --new-branch 
不 加 任何 选项 的 hg push 个 令 不 能 在 远程 版 本 库 创 建新 的 头 。 不 但 已 有 的 分 支 受 此 限制 ， 
而 且 在 远程 版 本 库 新 建 分 支 的 操作 也 包含 在 内 。 指 定 --new-branch 选项 可 以 在 远程 版 本 库 添 加 
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新 分 支 。 另 外 ， 即 便 指 定 了 --new-branch 选项 ， 我 们 依然 无 法 给 已 有 分 支 创 建新 的 头 ， 所 以 可 
以 放心 大 胆 地 创建 新 分 支 并 push 变更 。 还 有 一 点 要 注意 ， 就 算 我 们 已 经 将 本 地 创建 的 工作 分 支 


与 default 等 合并 ， 在 push 时 仍然 需要 指定 --new-branch 选项 。 


6.6.5 提交 设计 





如 何 对 待 设计 模板 以 及 媒体 文件 是 个 非常 难 的 点 ， 而 且 根 据 设 计 师 的 技术 以 及 工作 人 数 的 
不 同 ， 这 项 工作 的 难度 会 有 极 大 变化 。 一 般 说 来 ， 我 们 会 使 用 GUI 客户 端 通过 FTP、SCP 等 将 
文件 上 传 至 服务 器 ， 确 认 其 正常 工作 后 再 直接 在 服务 器 上 提交 文件 。 











€ 在 分 文中 进行 设计 

设计 模板 和 媒体 文件 也 要 和 源码 一 样 提交 到 分 文中 。 这 是 为 了 保证 在 与 系统 合并 失败 时 能 
立刻 还 原 到 正常 工作 的 状态 。 至 于 分 文 名 ， 我 们 建议 也 和 源码 一 样 ， 起 一 个 与 问题 编号 相对 应 
的 名 字 。 

如 果 设 计 和 需要 频 丝 更 改 但 系统 没有 变更 ， 那么 上 面 的 方法 会 显得 很 紧 琐 ,工作 量 很 大 。 这 
种 情况 可 以 创建 一 个 设计 专用 的 分 文 ， 把 所 有 和 设计 相关 的 变更 都 提交 到 这 里 ( 图 6.17 )。 

















$ cd example-prj 

$ lig branch 

default 

$ hg branch design # M default 创建 设计 专用 的 分 支 
$ hg commit # ma 











: J : l : : es 
历史 图 修订 版 ”分支 作者 时 间 标签 FEME ”描述 
Q 6+ design Shinya Okano 现在 * 工作 目录 x* 
Shinya Okano 57 秒 前 tip ^ draft idesign|tip ET STE) Ibid bd 

5 design Shinya Okano 101 秒 前 draft start branch design 
4 t5 Shinya Okano 6 分 钟 前 public — t5 多 开发 个 人 主页 功能 
3 t3 Shinya Okano 9 分 钟 前 public — t3 £43 制作 管理 界面 
2 t2 Shinya Okano 10 分 钟 前 public — 12 42 制作 首页 
1 ti Shinya Okano 14 分 钟 前 public — t1 #1 开发 登录 功能 
0 default Shinya Okano 2 小 时 前 public default init repo 











图 6.17 向 设计 专用 分 支 提 交 后 的 历史 图 


@ 伴随 系统 变更 而 产生 的 设计 提交 
在 添加 、 修 改 系统 源码 之 后 ， 如 果 需 要 对 设计 进行 添加 或 修正 ， 那 么 设计 师 必 须 先 将 查看 
设计 的 分 支 切换 至 已 提交 系统 源码 变更 的 分 支 ， 然 后 再 进行 自己 的 提交 。 
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6.6.6 ”分支 的 合并 
e 发 布 时 的 合并 

为 发 布 (交付 ) 在 工作 分 支 中 开发 的 功能 或 设计 ， 我 们 需要 先 将 工作 分 支 合 并 到 default 分 
支 ( 图 6.18 )。 





$ hg update default 

Song branch 

demais 

$ # 为 发 布 t5 分 支 中 的 变更 ， 要 将 该 分 支 合并 到 default 2x 
$ hg merge t5 

$ hg commit 





: i T ES Q E 
J ARTs aak SAYANG DS 
修订 版 ”分 支 作者 时 间 标签 ”开发 阶 和 ”描述 








7+ default ”Shinya Okano 现在 * 工作 目录 友 

7 default Shinya Okano 2 分 钟 前 tip |default|tip Ez: NE D 
6 design Shinya Okano 7 分 钟 前 public design #design 添加 布局 模板 

5 design Shinya Okano 8 分 钟 前 public start branch design 

4 t5 Shinya Okano 8 分 钟 前 public — t5 45 开发 个 人 主页 功能 

3 t3 Shinya Okano 10 分 钟 前 public — t3 #3 制作 管理 界面 

2 t2 Shinya Okano 10 分 钟 前 public — t2 #2 制作 首页 

1 ti Shinya Okano 12 分 钟 前 public — tí 44 开发 登录 功能 

0 default Shinya Okano 94 分 钟 前 public init repo 








6.48 t5 分 支 合 并 到 default 分 支 后 的 历史 图 


€ 用 来 追踪 最 新 变更 的 合并 

发 布 之 后 ， 未 发 布 的 分 文 也 必须 吸收 这 些 变更 ， 也 就 是 要 将 default 分 文 合 并 到 对 象 分 文 
(图 6.19 )。 把 default 分 文 的 成 末 吸 收 到 所 有 对 和 象 分 文中 能 市 来 很 多 好 处 ， 比 如 对 象 分 文 回 
default 分 文 合并 时 不 会 出 现 冲 突 。 为 外 ， 对 和 象 分 文 的 头 与 合并 后 的 修订 版 ， 即 default 分 文 的 新 
头 之 间 不 会 有 任何 差别 。 这 意味 着 只 要 合并 前 的 分 文通 过 了 测试 ， 合 并 后 也 必然 能 通过 测试 。 








$ hg update t3 

S 4 将 default 分 支 合并 到 t3 分 支 ， 使 上 3 分 支 吸 收 最 新 的 代码 
$ hg merge default 

$ hG Commie 








标签 ”开发 阶 和 ”描述 
* 工作 目录 女 
tjt 妇 merge default 


mH HÓA 分 支 ”作者 mA 
© 8+ t3 Shinya Okano 现在 
Shinya Okano 64 秒 前 ”tp 








7 default ”Shinya Okano 5 分 钟 前 public default 45 发 布 个 人 主页 功能 
6 design Shinya Okano 9 分 钟 前 public design #design 添加 布局 模板 
5 design Shinya Okano ”10 分钟 前 public start branch design 
[t 4 t5 Shinya Okano 11 分 钟 前 public — 15 45 开发 个 人 主页 功能 
3 t3 Shinya Okano 12 分 钟 前 public — 43 制作 管理 界面 
2 t2 Shinya Okano 13 分 钟 前 public — t2 #2 制作 首页 
1 t Shinya Okano 1553 hj public — tí #1 开发 登录 功能 
0 default ”Shinya Okano 97 分 钟 前 public init repo 








图 6.19 default 分支 合 并 到 t3 分 支 后 的 历史 图 
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如 何 处 理 已 经 无 用 的 分 支 


当 我 们 完成 某 部 分 开发 ， 将 与 问题 相对 应 的 分 支 合并 到 defaut 之 后 ， 这 个 分 支 就 没有 用 
了 。 但 是 ， 它 仍然 会 以 ( inactive ) 的 形式 残留 在 Mercurial 的 分 支 一 览 中 。 


$ hg branches 


default 7:a587bc0ebo8e 
design 6:e3£875bb6623 
3 3:0440d428d18a 
EZ 2:c4b2cd02f0c5 
t1 1:c65adedOfe1loó 
t5 4:9647e05b7580 (inactive) 已 经 合并 到 default 的 分 支 仍 会 留 在 一 览 表 里 


inactive (EFE ) JAZSAZROR D x E28 3f 2I R4 xx ( 3x EAE default) T4 BRE, AE 

尚未 被 发 布 的 分 支 也 可 能 进入 inactive 状态 。 如 果 不 分 清 已 经 发 布 完 毕 的 无 用 分 支 和 仍 要 使 用 
的 分 支 ， 就 很 可 能 酿 成 遗漏 发 布 等 事故 。Mercurial 有 一 个 专门 表示 无 用 分 支 的 状态 closed (已 
关闭 )， 我 们 可 以 将 没有 用 的 分 支 设 置 成 这 个 状态 。 关 闭 某 个 分 支 ( 转 入 closed 状态 ) 时 ， 需 要 
先 切 换 到 该 分 支 下 ， 然 后 在 提交 时 指定 --close-branch。 

$ hg update t5 

$ her branch 

ES 


$ hg commit --close-branch # 将 t5 分 支 转 为 closed 状 态 
$ hg branches # 已 被 close 的 t5 不 再 出 现在 一 览 表 中 


default 7:a587bc0ebe8e 
design 6:e3£875bb6623 
t3 3:0440d428d18a 
t2 2:c4b2cd02f0c5 
t1 l:c65adedOrelo 


closed JAS 5942) Xx & AR E WRTEhg branches m Si] ArH, ERTA SCRUMI 
除了 。 虽 然 不 关闭 分 支 不 会 对 开发 造成 影响 ， 但 考虑 到 事故 风险 ， 还 是 建议 各 位 将 无 用 的 分 支 
XHle 
6.6.7 ”集成 分 支 

在 统合 多 个 分 文 的 变更 内 容 时 ， 我 们 要 创建 一 个 集成 分 支 来 合并 它们 。 


© 创建 问题 
先 创建 问题 来 确定 分 文 编号 (图 6.20 )。 
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新 建 问题 HHE 日历” 新闻 文档 wid 文件 配置 


功能 #6 


用 来 确认 #1 238947 x 
让 tokibito 在 一 分 钟 之 前 添加 . 


状态 : 新 建 开始 日 期 : 
优先 级 : EB 计划 完成 日 期 : 
指派 给 : tokibito %o 完成 : 

类 别 : - 耗 时 : 

目标 版 本 : alphai 

描述 

#1 #3 








图 6.20 ”集成 分 支 的 问题 


@ 创建 集成 分 支 
创建 与 问题 编号 相对 应 的 集成 分 文 t6。 
$ hg update default 


$ hg branch t6 
Sna commit i ena 


将 要 集成 的 对 象 分 支 合 并 到 t6 (图 6.21 )。 














$ hg update t6 # 更 新 集成 分 支 
$ hg merge t1 # 合并 上 tl 分 支 
$ hg commit 
$ hg merge t3 # 合并 上 t3 分 支 
$ hg commit 
; 一 O : €) - 
J aer oa .-chseragaw' t. 
历史 图 修订 版 ”分 支 作者 时 间 标签 FEME HDA 
O 11+ t6 Shinya Okano 现在 * 工作 目录 * 
Shinya Okano 4 分 钟 前 tip ^ draft 6 |tip E Nue CES 
Q 10 t6 Shinya Okano 5 分 钟 前 draft #6 merge t1 
Ò 9 t6 Shinya Okano 6 分 钟 前 draft #6 创建 用 于 确认 的 分 支 
8 t3 Shinya Okano 23 分 钟 前 public — t3 £3 merge default 
7 default Shinya Okano 28 分 钟 前 public — default #5 发 布 个 人 主页 功能 
6 design ”Shinya Okano 32 分 钟 前 public design #design 添加 布局 模板 
5 design Shinya Okano 33 分 钟 前 public start branch design 
f, 4 t5 Shinya Okano 34 分 钟 前 public 15 开发 个 人 主页 功能 
3 t3 Shinya Okano 35 分 钟 前 public — 43 制作 管理 界面 
f 2 t2 Shinya Okano 36 分 钟 前 public — t2 42 制作 首页 
[$ 1 ti Shinya Okano 37 分 钟 前 public — tí £1 开发 登录 功能 
0 default Shinya Okano 2 小 时 前 public init repo 











图 6.21 将 对 象 分 支 合 并 到 用 于 查看 的 分 支 后 的 历史 图 
发 布 集 成 分 文中 的 全 部 内 容 时 ， 要 将 集成 分 文 t6 合并 到 default 分 支 。 





$ hg update default 
$ hg merge t6 d $E 
$ hg commit 
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集成 分 支 的 用 武之 地 


在 变更 内 容 出 现 冲突 ， 或 者 需要 在 特定 时 间 整 合 分 支 并 统一 发 布 等 情况 下 ， 集 成 分 支 会 显 
得 非常 好 用 。 

另外， 我 们 还 可 以 将 开发 完成 的 各 功能 分 支 先 合并 到 集成 分 支 ， 经 过 综合 测试 之 后 再 向 
default 合并 。 


6.7 小结 


本 章 就 Mercurial 的 使 用 方法 进行 了 说 明 ， 内 容 如 下 。 


。 钩子 功能 的 概述 与 活用 方法 
e 分 文 、 合 并 以 及 消除 冲突 的 方法 
e GUI 客户 闯 的 介绍 


另外 ， 还 对 多 人 开发 时 的 工作 流程 进行 了 说 明 ， 它 对 于 防范 冲突 及 运用 上 的 不 统一 有 着重 
要 的 意义 。 

如 今 ， 无 论 人 多 人 少 ，Mercurial 等 版 本 控制 系统 都 是 开发 中 必 备 的 工具 ， 能 否 用 好 版 本 控 
制 系统 已 成 为 左右 开发 效率 的 一 个 重要 因素 。 





Git 与 Mercurial 的 区 别 

Git 是 一 种 广 受 欢迎 的 分 布 式 版 本 控制 系统 ， 与 Mercurial 齐名 。 因 此 ， 我 们 能 看 到 很 多 Git 
与 Mercurial 的 命令 对 照 表 ， 这 就 是 为 Git 用 户 准 备 的 Mercurial 入 门 ， 或 者 是 为 Mercurial Fi P^ 
准备 的 Git 入 门 。 不 过 ， 如 果 让 Git 用 户 单 纯 根 据 命令 对 照 表 来 使 用 Mercurial， 或 者 反 过 来 让 
Mercurial 用 户 根 据 对 照 表 使 用 Git， 恐 怕 会 是 一 种 很 危险 的 行为 。 要 知道 ， 虽 然 Git 和 
Mercurial 同 为 分 布 式 版 本 控制 系统 ， 但 二 者 的 模型 并 不 相同 。 乍 看 上 去 ， 人 们 只 要 记 住 Git 中 
的 命令 和 Mercurial 中 的 命令 的 差别 ， 就 能 随便 在 二 者 间 换 着 用 了 ， 然 而 即使 有 对 照 表 ， 也 无 法 
改变 它们 不 同 的 本 质 ， 所 以 对 很 多 操作 都 是 都 会 产生 误解 ， 这 早晚 会 让 我 们 栽 跟头 。 举 个 例子 
更 能 说 明 Git 和 Mercurial 模型 间 的 差异 ，Mercurial 的 版 本 库 由 提交 对 象 的 图 表 构 成 ， 而 Git 的 
版 本 库 由 提交 对 象 的 图 表 和 引用 构成 。 

这 个 差别 最 明显 地 体现 在 对 分 支 的 看 法 以 及 同步 ( push/pull ) Eo 

Mercurial 的 分 支 本 质 上 是 给 提交 对 象 的 分 支 的 根部 命 了 名 。 严 格 说 来 ， 分 支 只 不 过 是 被 命 
了 名 的 各 个 提交 对 象 的 参数 。 但 是 ， 在 我 们 给 子 分 支 新 命名 之 前 ， 子 分 支 会 继承 父 分 支 的 名 字 ， 
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所 以 说 它 是 在 给 分 支 的 根部 命 
相对 地 ，Git 的 分 支 是 给 提交 对 象 的 图 表 的 最 新 端 命 了 名 。 这 是 一 个 每 次 提交 都 会 跟 看 最 新 


就 是 引用 的 删除 。 因 此 ，Mercurial 中 既 没 有 fast-foward 合并 也 没有 分 支 的 删除 ( fast-foward 
曾 被 导入 过 ， 但 与 Git 的 fast-foward 合并 仍 是 貌 相 似 而 质 不 同 )。 

如 果 把 push/pull 看 作 版 本 库 的 同步 ， 那 么 版 本 库 模 型 不 同 的 理由 将 更 加 显而易见 。 
Mercurial 的 版 本 库 是 提交 对 象 的 图 表 ， 因 此 只 需 将 提交 对 象 图 表 的 差别 同步 即 可 。push 操作 
中 只 需 发 送 对 方 没 有 的 那 部 分 图 表 ，pull 则 只 需 获 取 自 己 没 有 的 那 部 分 图 表 。 比 如 “ 删 际 历史 ” 
就 无 法 同步 。 就 算 我 们 加 上 -f 选项 ， 最 多 也 就 是 让 历史 受到 污染 ( 共享 了 多 余 的 子 图 表 )。 

Git 的 版 本 库 是 提交 对 象 的 图 表 和 引用 ， 因 此 双方 必须 保持 同步 。 切 换 引 用 的 必要 性 致使 
pull 需要 伴随 合并 操作 。 如 果 不 进 行 合 并 ， 该 分 支 就 将 出 现 remote 的 和 local 的 两 个 最 新 端 。 
但 是 Git 的 分 支 是 给 最 新 病 命 的 名 ， 这 融 要 求 一 个 分 支 只 能 有 一 个 最 新 站 。Git 的 pull 之 所 以 必 
须 以 分 支 为 单位 ， 恐 怕 就 是 因为 存在 这 样 一 个 需 主观 意识 判断 的 合并 过 程 。push 无 法 进行 主观 
意识 判断 ， 所 以 只 有 满足 fast-foward 合并 ( 不 需 主观 意识 判断 的 合并 ) 的 情况 下 才 人 允许 pusho 

在 更 改 历史 上 也 有 显著 委 异 。Git 在 日 常 使 用 中 充满 了 更 改 历史 ， 所 以 习惯 Git 的 人 在 用 
Mercurial 时 总 会 去 找 类 似 的 操作 。 但 是 ， 此 时 直接 按 对 照 表 操作 会 出 现 很 大 隐患 。 虽 然 Git 和 
Mercurial 中 都 有 “更 改 历史 ”， 但 二 者 实际 要 做 的 事 却 完全 不 同 。Git 是 新 建 图 表 并 将 引用 切换 
Aam, AE GC 局 动 之 前 仍然 保留 着 更 改 前 的 图 表 。 这 个 图 表 我 们 只 是 看 不 到 罢了 ， 但 
仍 可 以 通过 reflog 引用 它 。 相 对 地 ，Mercurial 是 实际 更 改 原 有 图 表 ， 即 向 图 表 添 加 新 的 子 图 表 
并 删除 日 的 子 图 表 。 一 个 由 图 表 的 引用 构成 ， 一 个 由 图 表 直 接 构成 ， 这 里 ， 二 者 的 差别 非常 显 
著 。 正 因为 如 此 ，Git 在 更 改 失败 时 只 需 引 用 reflog 寻找 更 改 前 的 修订 版 ( 分 支 的 最 新 端 )， 将 
这 个 修订 版 设置 为 该 分 支 的 头 即 可 完成 恢复 ， 但 Mercurial 就 必须 通过 bundle backup 恢复 旧 的 
子 图 表 ， 然 后 用 strip 命令 删除 新 的 子 图 表 。 可 见 ， 由 于 Git 与 Mercurial 在 模型 方面 存在 差异 ， 
导致 更 改 历史 有 着 实质 上 的 不 同 ， 更改 历史 失败 后 的 恢复 难度 及 安全 性 也 都 大 相 径 庭 。 所 以 各 
位 在 用 Mercurial 更 改 历史 时 ， 建 议 先 让 保存 原 历 史 的 选项 有 效 ， 等 确认 更 改 无 误 后 再 通过 
strip 命令 删除 旧 的 子 图 表 。 
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这 世上 有 痢 数 不 尽 的 项 目 ， 其 中 既 有 工作 项 目 ， 也 有 爱好 者 们 开发 的 开源 项 目 。 但 是 ， 这 
些 项 目 中 有 相当 大 一 部 分 都 没有 写 文 档 ， 或 者 事后 才 补 写 文 档 。 为 什么 开发 者 们 不 喜欢 写 文 档 
呢 ? 这 其 中 包含 者 怎样 的 问题 呢 ? 

本 章 中 ， 我 们 将 考察 何 种 环境 能 便于 开发 者 写 文 档 。 同 时 作为 例子 ， 还 将 介绍 文档 编辑 工 
H. Sphinx- 























7.1 要 记得 给 项 目 写 文 档 


项 目 文档 的 内 容 分 为 许多 种 。 虽 然 我 们 不 必 在 一 开始 就 把 所 有 文档 都 写 出 来 ， 然 而 一 旦 缺 
DRIEN, WAR A REEM H EFAA o 

《人 敏捷 建 模 : 极限 编程 和 统一 过 程 的 有 效 实践 》”( Scott Ambler 3E ) 一 书 是 这 样 回 答 “ 应 该 何 
时 写 文 档 ” 这 个 问题 的 。 





e 据 我 的 经 验 ， 当 实际 需要 时 再 去 做 模型 或 写 文档 比较 有 效 
e 只 在 过 到 麻烦 时 才 更 新 文档 
。 所 有 文档 部 应 该 尽量 晚 号 ， 应 该 留 到 马上 要 用 时 青 写 














所 以 我 们 需要 的 是 写 文 梢 的 时 间 计 划 ， 以 及 想 写 随时 就 能 写 的 环境 。 那 么 ， 什 么 样 的 环境 
能 让 人 随时 可 以 写 文档 ， 什 么 样 的 环境 又 能 让 人 有 动力 写 文档 呢 ? 或 者 反 过 来 说 ,妨碍 我 们 瑟 
文档 的 因素 都 有 哪些 呢 ? 下 面 我 们 就 从 Python 程序 员 的 视角 出 发 ， 考 察 妨碍 以 及 促使 我 们 写 文 
档 的 因素 。 


7.1.1 与 文档 时 不 想 做 的 事 


回顾 我 们 以 往 的 经 历 ， 那 些 没 有 写 文 档 的 情况 都 源 于 采 些 共通 的 理由 ， 下 面 就 介绍 其 中 几 
^ EHI e 


€ 不 想 用 与 文档 的 专用 工具 
写 文档 时 常用 的 工具 有 下 面 这 儿 种 。 





(D 原 书 名 为 Agile Modeling: Effective Practices for eXtreme Programming and the Unified Process, Scott W. 
Ambler /Ron Jeffries 著 ， 张 嘉 路 译 ， 机 械 工业 出 版 社 ，2003 年 1 月 出 版 。 译 者 注 
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文字 处 理 软件 
电子 制 表 软 件 
e Wiki 

e 其 他 综合 型 工具 











这 些 工 具 在 使 用 上 有 许多 地 方 都 和 我 们 平时 编程 用 的 编辑 骨 不 同 。 为 了 与 文 要 ， 必 须 用 月 
己 用 不 惯 的 编辑 表 或 工具 ， 这 成 了 与 文档 时 的 一 大 制约 。 我 们 更 布 望 能 用 平 芝 编程 用 的 编辑 胡 
号 文档 。 





€ 不 想 编辑 流水 账 似 的 单一 文件 

一 般 的 文字 处 理 软件 都 是 一 个 文件 管理 一 篇 文档 。 如 果 一 个 文件 纵向 延伸 得 较 长 ， 我 们 在 
编辑 或 显示 内 容 时 就 需要 将 其 滚动 到 特定 位 置 。 写 文章 过 程 中 一 旦 需要 对 其 他 地 方 进行 修改 ， 
就 必须 先 滚动 到 竺 修改 的 位 置 再 滚动 回来 。 这 种 操作 往往 每 写 一 篇 文档 就 要 经 历 许多 次 ， 而 且 
每 次 寻找 原先 的 位 置 都 很 麻烦 。 

然而 这 并 不 是 说 给 工具 加 个 界面 分 割 或 是 记忆 位 置 的 功能 就 能 行 的 。 问 题 的 根源 在 于 一 个 
文档 以 一 个 大 文件 的 形式 被 管理 着 。 这 就 像 一 个 程序 员 肯 定 会 觉得 可 分 割 的 源码 写 在 一 个 文件 
里 十 分 影响 效率 一 样 。 

要 解决 这 个 问题 ， 应 该 像 源码 一 样 将 文档 分 割 成 多 个 文件 管理 。 


























€ 不 能 用 Mercurial 等 管理 差别 ， 让 人 生 厌 

用 文字 处 理 软 件 写 出 的 文档 是 单一 的 二 进 制 文档 ， 不 管 我 们 在 里 面 修改 了 几 个 字 、 几 有 段 文 
革 或 者 几 幅 图 片 ，Mercurial 等 版 本 控制 系统 都 无 法 掌握 该 文件 中 的 被 修改 之 处 。 另 外 ， 如 采 有 
好 几 个 人 编辑 同一 个 文件 ， 很 容易 出 现 变更 冲突 ， 而 且 无 法 事后 自动 整合 双方 的 变更 。 

由 于 存在 着 这 些 问题 ， 我 们 很 难 放心 大 胆 地 去 添加 变更 。 











€ WYSIWYG 工具 在 涂饰 和 显示 上 很 费时 间 

WYSIWYG 是 What You See is What You Get 的 人 简写， 意思 是 “所 见 即 所 得 ”。 顾 名 思 义 ， 
H WYSIWYG 类 工具 写 文 档 时 能 和 耳 接 看 到 文档 最 终 的 显示 或 狐 饰 效果 。 

不 过 ， 这 有 时 也 会 让 我 们 在 写 文 章 时 分 心 去 考虑 显示 效果 ， 在 装饰 和 显示 上 花费 多 余 时 间 。 




















€ 不 想 把 参考 资料 和 程序 分 开 与 

极限 编程 等 敏捷 过 程 问世 以 来 ， 人们 对 程序 的 概念 发 和 后 了 变化 ， 那 就 是 从 “程序 是 按 设计 
号 的 一 成 不 变 的 东西 ” 变 成 了 “程序 是 阶段 性 变化 的 东西 ”。 

在 程序 阶段 性 变化 的 过 程 中 ， 文 档 必 须 跟 者 程序 的 脚步 进行 更 新 。 如 果 文 档 没 能 跟 上 程序 
的 变化 ， 看 文档 的 人 就 会 按照 陈旧 的 错误 信息 去 写 程序 ， 导 致 开发 无 法 顺利 进行 。 
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其 实 ， 人 人们 很 早 以 前 就 开始 什 助 专门 工具 来 解决 这 一 问题 了 。 这 些 工具 可 以 目 动 将 函数 年 
义 附近 的 API 文档 反映 到 参考 文档 中 。 但 可 惜 的 是 ， 有 些 编程 语言 无 法 使 用 这 类 工具 。 
所 以 我 们 需要 一 个 轻松 的 联动 机 制 ， 保 证 API 和 函数 的 实现 与 参考 文档 的 内 容 不 出 现 错位 。 














€ 不 想 写 没 人 看 的 文档 

没 人 看 的 文档 根本 没 必要 写 。 那 么 ,我们 应 该 如 何 分 辨 一 个 文档 有 没有 人 看 呢 ? 

写 出 来 的 文档 没 人 看 ， 主 要 原因 是 这 个 文档 的 目的 不 够 明确 ， 让 人 不 知道 是 写 给 谁 的 ， 为 
什么 写 的 。 所 以 在 项 目的 早期 阶段 就 该 给 文档 做 好 计划 ， 规 定好 什么 时 候 写 、 为 了 什么 目的 而 
号， 以 及 需要 写 什 么 内 容 。 

如 果 写 文档 的 目的 不 明确 ， 那 写 出 来 的 内 容 也 不 可 能 明确 。 有 了 一 个 明确 的 目的 ,不 但 能 
让 我 们 有 机 会 讨论 是 不 是 有 必要 与 这 个 文档 ， 而 且 写 起 来 脑 中 也 能 有 明确 的 内 容 。 

有 些 时 候 ， 我 们 会 遇 到 一 些 必 须 写 的 文档 ， 但 这 些 文 档 又 不 大 可 能 有 人 来 谈 。 我 们 也 要 
搞 清 楚 这 类 文档 是 为 谁 写 的 ， 为 什么 要 写 。 如 末 发 现 真 的 没 必 要 写 ， 可 以 跟 委 托 人 商量 之 后 再 


定夺 。 





























7.1.2 什么 样 的 状态 让 人 想 瑟 文档 


我 们 前 面 考 察 了 妨碍 写 文档 的 因素 ， 那 么 什么 样 的 情况 能 让 我 们 更 愿意 写 并 且 更 轻松 地 写 
文档 呢 ? 

消除 了 妨 但 因素 ， 掌 握 写 文档 时 的 关键 点 后 ， 以 下 几 个 “让 人 愿意 写 文 档 并 能 轻松 写 文 档 
的 条 件 ” 就 自然 而 然 地 浮现 了 出 来 。 














e 能 在 平时 用 的 编辑 各 上 写 文档 

把 文档 分 成 几 个 文件 来 瑟 

用 Mercurial 等 轻松 实现 版 本 管理 

集中 精神 编辑 内 容 ， 不 用 顾虑 效 饰 等 外 观 问 题 
e API 参考 手册 与 程序 的 管理 一 体 化 

e 平时 的 引用 可 通过 Web 浏览 硕 共 学 

e 在 提交 文档 时 可 转换 成 漂 完 整齐 的 单一 文件 

。 写 有 用 的 文档 


e 
zb amb amb amb 
ER EC GG GG 








那么 ， 满 足 这 些 条 件 的 文档 编辑 环境 有 哪些 呢 ? 
如 今 市 面 上 有 很 多 文档 编辑 工具 ， 它 们 各 有 各 的 特点 ， 也 各 有 各 的 长 项 与 短 项 。 这 里 我 们 
从 文档 结构 的 观点 出 发 ,， 来 了 解 一 下 这 些 特点 的 差异 。 
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Wiki 是 用 来 构筑 半 格 ( Semilattice ) 结构 文档 的 工具 。 半 格 结 构 没 有 起 点 和 终点 ， 是 一 种 各 
元 条 之 间 依 徘 引 用 链 相连 的 网 状 结构 。 这 种 结构 适合 在 某 一 主题 下 以 不 断 添加 关键 字 的 形式 编 
写 文档 片段 。 相 反 地 ， 它 不 适合 编写 那 种 要 从 涉 到 尾 按 顺序 阅读 并 提交 的 文档 。 

与 此 相对 的 还 有 构筑 树 结构 的 工具 。 树 结构 存在 起 点 ， 起 点 元 素 之 下 的 各 元 系 有 痢 固定 的 
从 属 关 系 。 以 图 书 为 例 ， 目 录 页 下 挂 着 各 章 的 标题 ， 各 章 下 又 挂 着 各 世 的 标题 。 树 结构 的 文档 
适合 从 头 到 尾 按 顺序 阅读 。 不 过 ， 单纯 的 树 结构 在 很 多 情况 下 都 不 大 好 用 ， 所 以 我 们 会 添加 一 
个 到 任意 元 素 的 引用 ， 将 树 结构 改造 成 网 状 结构 。 虽 然 树 结 构 看 上 去 优 于 半 格 结构 ， 但 它 必 须 
有 一 个 主干 ， 所 以 不 适合 用 来 当 没 有 固定 结构 的 字典 。 

接 下 来 我 们 将 学 习 Sphinx， 它 是 构筑 树 结 构 文档 的 文档 编辑 工具 。 

Sphinx 是 用 Python 编写 的 工具 ， 用 来 构建 多 个 以 reStructuredText 语法 编写 的 文本 文件 ， 将 
它们 转换 为 HTML 或 PDF 等 格式 。Sphinx 可 以 将 树 的 各 个 元 素 分 割 成 多 个 文件 进行 管理 。 田 
外 ， 这 球 工 具 的 功能 和 特征 满足 刚才 我 们 说 过 的 “让 人 愿意 写 文 档 并 能 轻松 写 文档 的 条 件 ” 中 
的 许多 条 ， 甚 至 能 让 人 更 加 主动 地 想 要 与 文档 。 





















































NOTE 
当然 ， 只 要 讲究 方法 、 肯 下 功夫 ， 不 管 什 么 工具 都 有 可 能 让 我 们 达到 目的 ， 但 其 过 程 是 否 
给 人 带 来 压力 就 男 当 别论 了 。 我 们 即将 学 习 的 Sphinx 也 完全 不 是 那 种 在 GUI 中 随便 一 操作 就 能 
写 文 草 的 工具 ， 但 它 适合 像 写 程序 一 样 结构 化 地 写 文 草 。 
接 下 来 ,我 们 将 先 来 了 解 一 下 Sphinx 的 基本 使 用 方法 。 然 后 根据 本 市 列 出 的 这 些 条 件 ， 分 
条 学 习 如 何 用 Sphinx 实现 它们 。 


7.2 Sphinx 的 基础 与 安装 














Sphinx 是 一 球 文 档 编 辑 工 具 ， 具 有 十 分 全 面 的 文档 资料 。 





Sphinx 官方 网 站 
http://www.sphinx-doc.org/en/stable/ 


Sphinx 使 用 手册 
http://www.sphinx-doc.org/en/stable/contents.html 
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e Sphinx HJ ZA 

e reStructuredText AT] 

e 用 Sphinx 编写 结构 化 文档 的 流程 
e Sphinx 扩展 


7.2.1 Sphinx 的 安装 


Sphinx 的 安装 流程 并 不 复杂 ， 但 各 位 要 尽量 使 用 最 新 版 本 。 这 里 建议 各 位 使 用 最 新 的 
Sphinx-1.3 系列 (截至 2014 Æ 12 月 时 的 最 新 版 本 )。 
安装 用 以 下 命令 执行 。 


$ pip ingtall spaim 


这 样 ， 我 们 就 装 好 了 Sphinx 关联 的 程序 包 ， 现 在 可 以 用 sphinx-quickstart 命令 了 。 
sphinx-quickstart 命令 能 自动 生成 启动 Sphinx 所 需 的 数 个 文件 。 具 体 执 行 方法 如 LIST 7.1 
所 示 。 


加 LIST 7.1 sphinx-quickstart 


$ sphinx-quickstart -q -p SW-Project -a BeProud -v 1.0 sw-project 
Creating file sw-project/conf.py. 

Creating file sw-project/index.rst. 

Creating file sw-project/Makefile. 


Creating file sw-project/make.bat. 
Finished: An initial directory structure has been created. 


You should now populate your master file sw-project/index.rst and create other 
documentation d 
source files. Use the Makefile to build the docs, like so: 
make builder 


where "builder" is one of the supported builders, e.g. html, latex or linkcheck. 


$ ls sw-project/ 
uile) cont. py Incek- rst make bat Makefile statie _ templates 


执行 完毕 后 ，sw-project 日 录 下 就 生成 了 了 Sphinx 项目， 然后 就 可 以 通过 make html 构建 
Sphinx 了 。Sphinx 写 文档 的 标准 扩展 名 为 “.rst”， 所 以 这 里 会 生成 index.rst 文件 。 

如 采 不 加 任何 选项 下 接 执 行 sphinx-quickstart， 则 会 以 对 话 形式 生成 Sphinx 项 目 。 
这 种 情况 下 ， 计 算 机 将 以 对 话 形式 提出 几 项 询问 ， 其 中 Project Name, Author, Version 这 3 个 
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问题 需要 由 我 们 来 输入 ， 其 他 问题 则 只 需 根 据 实 际 情况 选择 Y 或 N 即 可 。 在 LIST 7.2 的 例子 
中 ， 我 们 让 文件 生成 在 sw-project 目录 下 。 


EJ LIST 7.2 sphinx-quickstart 对 话 模式 


$ sphinx-quickstart 
Welcome to the-sSphrnx 4$.5 quurickstazxt en 


- ( 中间 省 略 ) - 
> Root path for the documentation [.]: sw-project 
- (中 间 省 略 ) - 


> Project name: SW-Project 


> Author name(s): BeProud 
- ( 中间 省 略 ) - 

> Project version: 1.0 

- (rig eil ) - 


$ ls sw-project 


uile) å coni py index ret make bart Ep cod cc tes 


通过 sphinx-quickstart 设置 的 内 容 全 都 记录 在 conf.py 文件 中 ， 所 以 日 后 想 更 改 设 置 时 需要 
编辑 conf.py 文件 。 男 外 ， 如 果 想 用 中 文 版 的 Sphinx， 可 以 在 conf.py 文件 中 作 如 下 设置 
( LIST 7.3 ), 








回 LIST 7.3 conf.py 


language = "zia CN' 





详细 安装 流程 以 及 Sphinx 的 初始 设置 请 参考 以 下 网 站 。 


Sphinx 入 门 
http://www.sphinx-doc.org/en/stable/install.html 


7.2.2 reStructuredText AT] 





Sphinx 要 用 reStructuredText ( reST ) 语法 写 文 档 。 这 里 我 们 学 习 儿 个 具有 代表 性 的 reST 5 
法 ( LIST 7.4 )。 
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加 LIST 7.4 sample.rst 


: MA1: FBJIJRAR 1 
: MA2: SEERAUSSIALA 2 
: 项 目 3: 字段 列表 内 容 3 


节 标 题 1 


节 内 第 一 个 段落 的 文章 。 
换行 会 被 忽略 。 


第 二 个 段落 的 文章 。 
用 空 行 划 分 段落 。 
空 行 至 少 为 一 行 ， 输 入 多 少 行 效 果 剖 一样 。 


H. 自动 编号 的 有 序列 表 
#. 自动 编号 的 有 序列 表 


没有 编号 的 无 序列 表 按 以 下 格式 书写 。 


+ 低 一 级 的 无 序列 表 
+ 低 一 级 的 无 序列 表 


可 以 给 词汇 添加 多 种 特殊 意义 。 


-wx 强调 xx 

- * 斜体 * 

- ”显示 为 字符 串 

- ` RFI EA 

- “链接 字符 申 B<http://docs.sphinx-users.jp>、” | 
- :doc:`index` 到 对 象 文 件 的 和 链接。 会 自动 替换 为 章 标题 。 


. _ 链接 字符 申 A: http://sphinx-users.jp 
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为 了 从 首页 链接 到 这 个 sample.rst 文件 ， 我 们 在 index.rst 中 作 如 下 描述 ( LIST 7.5 )。 


© LIST7.5 index.rst 


. toctree:: 


:maxdepth: 2 


sample 


这 样 就 可 以 构建 sample.rst 了 。 接 下 来 我 们 执行 make html C LIST 7.6 )。 


EJ LIST 7.6 make html 


S make html 





HERRA] " builld/htm" HRK Fo MAFII "^ build/html/sample.html" T UA 
到 如 图 7.1 所 示 的 输出 结 





SW-Project 1.0 文档 > 
内 容 目录 章 标 题 


章 标 题 


。 节 标 题 1 项 目 1: 字段 列表 内 容 1 















项 目 2: 字段 列表 内 容 2 
项 目 3: 字段 列表 内 容 3 
Tos 
快速 搜索 节 标 题 1 


EC 


节 内 第 一 个 段落 的 文章 。 换行 会 被 忽略 。 
输入 相关 的 术语 ， 模 块 ， 类 或 者 函数 M e .0 . g 
名 称 进行 搜索 第 二 个 段落 的 文章 。 用 空 行 划分 段落 。 空 行 至 少 为 一 行 ， 输 入 多 少 行 效果 都 一 样 。 


1. 规定 编号 的 有 序列 表 

2. 规定 编号 的 有 序列 表 
1. 自动 编号 的 有 序列 表 
2. 自动 编号 的 有 序列 表 


没有 编号 的 无 序列 表 按 以 下 格式 书写 。 


。 无 序列 表 

。 无 序列 表 
o 低 一 级 的 无 序列 表 
o 低 一 级 的 无 序列 表 

可 以 给 词汇 添加 多 种 特殊 音义。 

。 强调 

. RE 

。 显示 为 字符 串 

。 链接 字符 串 A 

。 链接 字符 串 B 

。 Welcome to SW-Project's documentation! 到 对 象 文件 的 链接 。 会 自动 蔡 换 为 章 标题 。 


SW-Project 1.0 文档 » 


© 版权 所 有 2016, BeProud. 由 Sphinx 1.3 创建 。 


7.1 Sphinx 输出 示例 





reStructuredText AT] 
http://www.sphinx-doc.org/en/stable/rest.html 





7.2.8 用 Sphinx 写 结构 化 文档 的 流程 
Sphinx 在 很 多 地 方 都 引入 了 结构 化 的 概念 ， 因 此 它 为 写 文档 的 人 提供 了 一 个 方便 写 文 档 且 
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方便 整理 的 环境 。 下 面 就 是 利用 Sphinx 提供 的 结构 化 来 编写 文档 的 流程 。 


@ 标题 与 元 素 
我 们 从 零 开 始 与 文档 时 ， 往 往 会 不 知 从 何 写 起 。 虽 然 想 到 什么 写 什 么 不 失 为 一 种 办 法 ,但 
最 好 还 是 先 列 出 标题 大 纲 ， 整 理 一 下 文档 内 容 的 结构 (LIST7.7 )。 





B LIST7.7 先 逐 条 列 出 标题 


* 标题 1 


* 标题 2 
* 标题 3 


然后 再 将 想到 的 东西 填 进 适当 位 置 ， 使 文章 逐渐 丰满 起 来 ( LIST 7.8 )。 





Ej LIST 7.8 给 标题 添加 内 容 


* 标题 1 


| 标题 1 
| 标题 2 
| 标题 3 


* 
mo mo Eol 


在 这 里 逐渐 补充 副标题 3 的 内 容 。 
如 果 想 到 了 与 副标题 3 无 关 的 内 容 ， 
就 补充 到 其 他 合适 的 地 方 。 


* 


* 











这 种 具有 了 明确 父子 关系 或 兄弟 关系 的 文本 称 为 结构 化 文本 。 本 例 中 既 用 了 标题 和 内 容 这 
种 具有 明显 父子 关系 的 逐条 列 记 ， 又 用 了 空格 纵 进 的 文本 。 在 写 文档 时 ， 如 末 我 们 脑 中 没有 一 
个 明确 的 框 染 ， 束 需要 不 断 重 复 这 种 堆砌 “标题 ”与 “表达 内 容 的 元 系 ”( 本 例 中 是 副标题 ) 的 
Re 
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€) 单一 文件 内 的 结构 化 

用 reStructuredText 写 的 文章 会 被 结构 化 ， 看 上 去 条 理 分 明 。 比 如 用 reStructuredText 描述 会 
以 记录 并 请 加 到 邮件 中 ， 收 件 人 就 可 以 直接 流畅 地 阅 旋 。 

结构 化 让 各 条 信息 之 间 的 关系 更 加 明确 ， 并 列 、 父 子 结构 一 目 了 人 然 ， 而且 信息 的 换 位 与 重 
排 也 能 很 轻松 地 进行 。 

按照 这 种 结构 化 规则 写 出 的 文本 具有 树 结 构 ( 图 7.2 )。 








index.txt 





7.2 文本 的 树 结构 


€ 文件 与 目录 的 结构 化 

在 写 文 档 的 过 程 中 ,会 过 到 标题 下 的 内 容 过 于 详细 的 情况 ， 这 会 破坏 文章 的 平衡 性 。 男 外 ， 
如 果 我 们 只 往 一 个 文件 里 写 ， 文章 的 主干 就 会 越 来 越 模糊 ， 事 情 也 会 越 来 越 讲 不 清楚 。 当 文 
草 达 到 一 定 规模 ， 其 内 容 需 要 分 类 分 割 时 ， 我 们 可 以 根据 文件 和 目录 将 其 分 割 并 结构 化 。 分 割 
后 ， 主 干 与 分 文 之 间 必 须 保持 一 个 父子 关联 。 这 样 一 来 ， 文 件 就 能 在 分 割 之 后 仍 保 持 树 结构 了 
(图 7.3 )。 











172 | 第 2 部 分 团队 开发 的 周期 


index.txt 





title2.txt 
m 





图 7.3 在 维持 树 结构 的 前 提 下 分 割 文件 

等 到 文件 数量 多 起 来 ， 可 以 将 文件 分 组 ， 按 目录 进行 结构 化 。 总 而 言 之 ， 束 是 灵活 运用 文 
件 与 目录 ,不 汤 将 结构 化 向 前 推进 。 

完 将 文档 的 半 或 方 按 目录 或 文件 进行 分 割 ， 这 有 助 于 我 们 今后 对 革 广 进行 增 减 与 重 排 。 为 
外 ， 由 于 文件 被 分 成 了 多 个 ， 所 以 可 以 1 人 或 多 人 同时 编辑 多 个 地 方 。 举 个 例子 ， 如 果 我 们 同 
时 想到 好 几 个 点 ， 那 么 可 以 同时 打开 多 个 文件 做 记录 ， 这 要 比 编辑 单一 文件 更 容易 找到 信息 的 
位 置 ， 而 且 能 很 轻松 地 定位 到 之 前 中 靳 工作 的 地 方 。 

Sphinx 能 将 所 有 文档 文件 组 合 到 一 个 树 结构 中 。 这 样 ， 所 有 文件 都 被 排 成 了 一 个 序列 ， 并 
以 让 人 能 从 上 至 下 阅读 的 格式 进行 输出 。 该 定义 需 在 文档 中 用 . . toctree:: 指令 描述 。 

只 要 有 了 toctree 这 样 一 个 主干 ， 文 档 就 能 在 被 分 割 成 多 个 文件 之 后 仍 保持 其 结构 。 











@ 网 状 结构 
只 要 按照 一 定 的 规则 给 文档 加 入 关键 字 或 到 其 他 草 市 的 跳 转 ， 就 能 实现 Wiki 那 种 灵活 的 网 
状 结构 。 脚 注 、 交 又 引 用 、 术 语 集 、 索 引 等 就 是 此 类 网 状 结构 CHI 7.4 )。 








A œ 
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index.txt 


( toctree 






从 


A 
title2.txt 
M y 

P4 
* 


从 






p 4 
title1.txt r 
4 4 


H 


标题 1 xl: 





7.4 结构 化 文档 的 网 状 结构 


链接 可 以 让 我 们 更 容易 地 在 文档 中 找到 想 找 的 信息 。Sphinx 会 为 我 们 提供 清晰 的 术语 集 、 
API 参考 手册 等 信息 ， 我 们 可 以 利用 这 个 功能 来 统一 术语 。 

比如 在 号 文革 的 过 程 中 发 现 有 术语 需要 统一 ， 我 们 可 以 和 完 用 term: ` A38 ^ 的 形式 将 该 
术语 写 下 来 。 由 于 Sphinx 在 make 时 会 提示 该 术语 没有 对 应 的 术语 说 明 ， 所 以 我 们 完全 可 以 把 
写 术语 说 明 的 工作 放 到 最 后 再 做 ,这样 既 不 会 打 靳 写 文革 的 进度 ， 也 不 必 担 心 出 现 遗 汤 。 

此 外 ， 我 们 还 可 以 用 :doc:`../sub/index` 这 样 的 形式 指定 引用 页 面 的 相对 路 径 ， 
Sphinx 在 make 时 会 自动 将 该 页 面 的 标题 和 链接 填充 到 这 里 。 




















@ 结构 化 的 3 个 阶段 
正如 我 们 前 面 所 介绍 的 ， 结 构 化 分 为 如 下 3 个 阶段 (图 7.5 )。 





中 单一 文件 内 的 结构 化 
D 分 割 成 多 个 文件 / 目录 并 结构 化 
O 连接 成 无 直接 父子 关系 结构 的 网 络 
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Level 1 
单一 文件 


Level 2 


多 个 文件 /目录 


Level 3 
网 络 


7.5 ”结构 化 的 3 个 阶段 


通过 这 样 从 内 到 外 地 让 文章 结构 化 、 分 组 化 ， 文 档 将 卓然 而 然 地 得 到 整理 ， 写 起 来 当然 也 
会 轻松 许多 。 男 外 ，Sphinx 以 树 结构 为 基础 ， 与 Wiki 那 种 仪 由 网 络 形 成 的 半 格 结构 不 同 ， 阅 读 
起 来 主 次 分 明 ， 易于 理解 。 以 树 结 构 为 主 让 文档 整体 有 了 一 根 消 梁 ， 然后 在 各 结构 之 间 添 加 神 
经 网 络 ， 这 样 可 以 加 强 文档 阅读 时 的 灵活 性 。 





7.8.4 Sphinx 扩展 


Sphinx 捆绑 了 TeX HEN RSESEU JE, ds schESRMUAEORESB — TAB fies AEN HEU 
括 流程 图 、 序 列 图 等 图 表 的 植 人 扩展 、UML MAL RR HTML 模板 变更 等 。 当 然 我 们 还 
可 以 目 己 开发 扩展 。 

扩展 功能 在 Sphinx 的 confpy 文件 中 设置 。 比 如 我 们 可 以 像 LIST 7.9 这 样 描述 。 


© LIST 7.9 conf.py 


extensvons = [l'spbsnxext.pngmatB' "'sphanx-ext.todo'j 'sphrnx-.ext-autedoce'] 


这 样 就 激活 I Sphinx 主体 程序 自 带 的 3 个 扩展 功能 。 这 里 将 介绍 的 是 sphinx.ext.pngmath 。 

pngmath 扩展 用 来 在 文档 中 以 图 片 形式 显示 数学 公式 。 我 们 只 要 在 文档 中 描述 了 代表 数学 
公式 的 字符 串 ， 该 扩展 就 会 在 构建 时 将 它们 转换 为 PNG 图 像 文件 植 和 文档。 不 过 ， 用 这 个 扩展 
的 前 提 是 具备 LaTeX 环境 "， 

我 们 在 文档 中 作 如 下 描述 ( LIST 7.10 )。 














EJ LIST 7.10 math.rst 


(D Sphinx-users.jp 网 站 上 有 介绍 LaTeX 环境 的 安装 流程 。 一 一 编者 注 


y 
J 
my 
d} 
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meeme (2 20 2 


构建 之 后 会 显示 如 图 7.6 所 示 的 数学 公式 。 


(a -- b? — a? + 2ab + b? 





7.6 sphinx.ext.pngmath 的 数学 公式 绘图 





Sphinx 对 数学 公式 的 支持 
http://www.sphinx-doc.org/en/stable/ext/math.html 

经 由 LaTeX 输出 PDF 文档 ”( 日 语 ) 
http://sphinx-users.jp/cookbook/pdf/latex.html 








7.3 导入 Sphinx 可 解决 的 问题 与 新 出 现 的 问题 


本 章 最 开始 就 列举 了 下 列 “ 让 人 愿 意 写 文档 并 能 轻松 写 文 档 的 条 件 ”。 





e 
zb amb amb amb 
ER EC GG CC 


在 平时 用 的 编辑 硕 上 与 文档 

把 文档 分 成 几 个 文件 来 号 

用 Mercurial 等 轻松 实现 版 本 管理 

集中 精神 编辑 内 容 ， 不 用 顾虑 猴 饰 等 外 观 问 题 
。 API 参考 手册 与 程序 的 管理 一 体 化 

e 平时 的 引用 可 通过 Web 20 9 dg 

。 在 提交 文 梢 时 可 转换 成 深 亮 整齐 的 单一 文件 格式 
。 写 有 用 的 文档 








现在 我 们 分 条 学 习 如 何 用 Sphinx 实现 这 些 条 件 。 


O 该 部 分 内 容 是 Sphinx-users.jp 网 站 针对 日 语文 档 的 生成 这 种 情况 而 编写 的 。 英 语文 档 的 生成 则 参照 
Sphinx 手册 即 可 。 一 一 编者 注 
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7.3.1 由 于 是 纯 文 本 ， 所 以 能 在 平时 用 的 编辑 器 上 写 文档 

想必 程序 员 都 有 过 读 纯 文本 文档 的 经 历 。 特 别 是 开源 程序 的 附属 文档 ， 其 中 有 许多 图 表 都 
是 由 纯 文 本 表达 ， 它 们 和 程序 一 起 被 视 为 源码 进行 管理 。 为 什么 很 多 人 选择 用 这 种 方法 写 文档 
呢 ? 理由 有 以 下 几 点 。 











。 不 必 信 助 特 殊 工具 ， 仪 用 纯 文本 就 能 表达 结构 或 图 表 

e 编写 、 阅 贤 文 档 不 依赖 特殊 工具 ， 无 论 该 工具 有 偿 无 傍 
e 可 以 用 源码 管理 工具 来 管理 文本 文件 的 变更 

e 写 代码 和 瑟 文 档 都 能 在 惯用 的 编辑 各 上 进行 




















可 见 ， 用 纯 文本 写 文档 并 不 是 心血 来 潮 ， 它 是 有 明确 优势 的 。 

Sphinx 就 是 用 纯 文 本 写 文 档 。 用 户 按照 特定 的 规则 描述 纯 文本 ， 然 后 Sphinx 来 解释 该 规 
则 ， 将 文本 以 HTML, PDF 等 格式 输出 ， 这 就 是 Sphinx 的 作用 。 

图 片 要 以 独立 文件 的 形式 统一 保存 ， 跟 文档 的 文本 文件 放 在 同一 目录 或 其 子 目 录 中 (LIST 
7.11 )。 这 样 ， 一 旦 日 后 遇 到 容量 等 问题 需要 改变 大 小 或 格式 时 ， 能 方便 地 统一 转换 。 











加 LIST7.11 用 于 植 入 图 片 的 figure 指令 
方便 多 人 同时 编辑 ， 也 便于 用 版 本 管理 工具 进行 管理 


. figure:: images/7-sphinx-vcs-manage.png 


Fi Mercurial E = Sphinx Xf 


7.3.2 fe E EET, MUR RRRA, AAE a DS 


外 观 问题 
Sphinx 的 以 下 特征 实现 了 信息 (Data ) 与 视图 ( View) 的 分 离 ， 所 以 我 们 能 集中 精神 写 
文档 。 
e 用 reStructuredText 写 文档 看 不 到 最 终 的 显示 效果 
。 吕 以 集中 精力 描述 逻辑 结构 化 的 正文 
e 最终 的 设计 由 Sphinx (或 者 由 制定 主题 的 设计 师 ) 调整 
。 相 当 于 其 他 文档 编辑 工具 的 大 纲 功 能 











前 面 我 们 学 习 了 如 何 用 reStructuredText 写 文档 以 及 如 何 用 Sphinx 构建 并 输出 。 总 而 言 之 ， 
我 们 可 以 把 装饰 和 外 观 交 给 Sphinx 人 处理， 自己 集中 精神 写 文章 内 容 。 





第 7 章 ， 完 备 文档 的 基础 “| 177 


比如 ， 我 们 要 用 Sphinx 编写 如 下 会 议 记 录 (LIST 7.12 )。 


加 LIST 7.12 会 议 记 录 示 例 


: 参加 者 : SW 商事 平野 、BP 清水 川 、BP 小 田 切 、BP AE 
: BARKE : 2015/2/17(.—) 10:00 ~ 11:30 
: 场地 : SW 商事 的 会 议 室 


今日 议 各 


ESSE 
2. 面向 开发 者 的 程序 库 的 开发 情况 
3. 11 HET HT 


KEF: 
Python ZU 0 e TA Django E =i GoogleAppEngine i A. 
参与 了 许多 面向 Python/DJjango 的 开源 程序 库 的 开发 ， 
其 中 以 面向 移动 电话 的 开发 支持 库 django-bpmobile 为 代表 。 


这 篇 会 议 记 录 是 用 reStructuredText 写 的 。 如 果 用 Sphinx 构建 ， 可 以 获取 如 图 7.7 ~ 图 7.9 
所 示 的 经 过 整理 的 HTML 或 PDF 文件 。 
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2015/2/17 会 议 记 录 
参加 者 : SW 商事 平野 、BP 清 水 川 、BP 小 田 切 、BP 风 野 
日 期 及 时 间 : 2015/2/17 (—) 10:00 - 11:30 
场地 : SW 商事 的 会 议 室 


今日 议程 











1. 介绍 新 成 员 
2. 面向 开发 者 的 程序 库 的 开发 情况 
3. 11 月 起 的 工作 方针 


pg 
入 相关 的 术语 ,模块 ， 类 或 者 函数 Python 经 验 10 年 。 平 时 用 Django 框架 和 GoogleAppEngine 进 行 开 发 。 参 与 了 许多 面向 
名 称 进 行 搜索 on om SES 其 中 以 面向 移动 电话 的 开发 支持 库 django-bpmobile 为 
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7.7 Sphinx 的 HTML 输出 ( default 主题 ) 
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内 容 目 录 
2015/2/17 会 议 记录 












2015/2/17 会 议 记 录 
a 今日 议程 
。 介绍 新 成 员 


参加 者 - SW 商 事 平野 、BP 清 水 川 、BP 小 田 切 、BP 冈 野 
SEARO 2015/2/17 (Z) 10:00 ~ 11:30 
场地 - SW 商事 的 会 议 室 

Welcome to SW-Project's 今日 议程 

documentationl 








1. 介绍 新 成 员 
2. 面向 开发 者 的 程序 库 的 开发 情况 








AutoDoc 范 例 3. 11 月 起 的 工作 方针 
介绍 新 成 员 
显示 源 代码 
内 野 : 
Python 经 验 10 年 。 平 时 用 Django 框 架 和 GoogleAppEngine 进 行 开发 。 参 与 了 许多 面向 
E Python/Django 的 开源 程序 库 的 开发 ， 其 中 以 面向 移动 电话 的 开发 支持 库 django- 














Tm i bpmobile 为 代表 。 
输入 相关 的 术语 ， 模 块 ， 类 或 者 函数 


名 称 进行 搜索 


EAT AA 


© 版 权 所 有 2016, BeProud. 由 Sphinx 1.3 创建 。 





SW-Project 1.0 文档 > 








7.8 Sphinx 的 HTML 输出 ( bizstyle 主题 ) 


Chapter 1 


2015/2/17 会 议 记 录 


参加 者 SW 商 可 平野、BP 清 水 川 、BP 小 田 切 、BP 冈 野 
日 期 及 时 间 2015/2/17 ( — ) 10:00 ~ 11:30 
场地 SW 商 事 的 会 议 室 


1.1 今日 议程 


1. 介绍 新 成 员 
2. 面向 开发 者 的 程序 库 的 开发 情况 
3. 11 月 起 的 工作 方针 


1.2 介绍 新 成 员 

冈 野 : Python 经 验 10 年 。 平 时 用 Django 框 架 和 GoogleAppEngine 进 行 开发 。 参 与 了 许 
多 面向 Python/Django 的 开源 程序 库 的 开发 ， 其 中 以 面向 移动 电话 的 开发 支持 库 
django-bpmobile25 ft, 





7.9 Sphinx 的 PDF 输出 ( latexpdfja ) 


JL), Sphinx 还 搭载 了 强大 的 代码 高 亮 功能 ， 它 可 以 给 程序 代码 等 自动 搭配 颜色 ， 提 高 可 
读 性 。 

代码 高 亮 功能 由 Sphinx 捆绑 的 Pygments 提供 。 文 持 的 格式 方面 ， 编 程 语 言 、 设 置 文件 、 
HTML 模板 等 加 起 来 有 200 种 左右 ， 而 且 仍 在 增加 (图 7.10 ~ FR 7.12 )。 





(D nttp://pygments.org/docs/lexers/ 
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Windows ini 


[loggers] 
keys-root 


[handlers] 


keys-consoleHandler 


[formatters] 
keyszsimpleFormatter 


[logger. root] 
level INFO 


handlers-consoleHandler 





图 7.10 Windows ini 格式 的 高 亮 


Python 


class Foo(object): 


def — init (self, value): 
print "value = $d' % value 
raise Not [mplementedError(u' EmptyClass' ) 





7.11 Python 代码 的 高 亮 


Apache Conf 


«VirtualHost *:80> 
Serverhdmin webmaster@dummy-host . example.com 
DocumentRoot "/var/www/samp|e/" 


ServerName dummy-host . example.com 

ServerÁl ias www.dummy-host . example. com 

ErrorLog "logs/dummy-host . example. com-error. log" 

CustomLog "logs/dummy-host . example.com-access.|log" common 
X«/NirtualHost? 





7.12 Apache conf 格式 的 高 亮 


7.3.3 可 根据 一 个 源码 输出 PDF 等 多 种 格式 


剖面 我 们 了 解 了 纯 文 本 的 好 人 处 以 及 文件 分 割 的 好 处 。 不 过 ， 我 们 仍然 希望 在 印刷 和 交付 时 ， 
文档 能 被 整合 成 一 个 文件 。 
另外 ， 虽 然 文本 文件 形式 的 文档 与 PDF 文档 有 大同 样 的 信息 价值 ， 但 文本 文件 形式 的 文档 
总 会 给 人 一 种 廉价 感 。 为 避免 因此 而 受到 影响 ,我 们 在 上 交 文 档 时 最 好 准备 一 份 经 过 简单 排版 
和 装饰 的 PDF 文件 。 
Sphinx 可 以 将 同一 份 源码 文件 转换 成 多 种 不 同 的 格式 。 输 出 格式 支持 HTML, PDF, 
EPUB, man, LaTeX, HTML Help ( chm ) 等 (图 7.13), BSR, 导入 目 制 的 扩展 后 ， 还 可 以 文 
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持 一 些 原本 不 文 持 的 格式 。 





T) Python 开发 实 或 【 样 书 ) .pdf - Adobe Acrobat Pro 
LHA SBE WEA 文档 (D) 注释 (C) 表单 (RY) IDEM 高 级 (名 ”窗口 (IW) 帮助 (H) 











(dem. Dar Qur- 重奏 JA az [pee psn Fa- 
(edu e» >” = Ev 


02 开发 Web 应 用 程序 25 26 第 一 部 分 ”使 用 Python 开发 


[E] 版 权 -1 zx (à Webi*& 948 JE Web Eg 4-980 9609 (96 && FR UCRRLIT TE UR UR FP 
= [E] 3 版 权 声 明 目 就 上 而 流程 中 提 到 的 术语 ， 读 考 可 以 查阅 下 而 这 张 表 。 
TE weed DATOR US BEEN AUREUS, WEEREAUETML., CSS... 型 片 等 内 容 信 
i3] hi 43 Fs BH BR SRRXAAPHUM 
Mane URL Urien Rescurce Locis. (LA AGEIN E ET emer E GL UP 
E 3 前言 ERmOTOTYt" 
n E 前 PREHRA TAN RLP AA www depron jp EA JOY ) 
AREARE RRAN EPEEN EE NES 
+ [E 4 导读 通信 对 疹 计 算 槐 在 网 乡 上 的 地 站 。《〈 以 Fw4 地 址 为 例 ， 一般 表示 为 192 1680 1 这 
RSS MEUBLOLPUCE EI. Áo ecEF MER TEM) 
+ [Ej 5 目录 Hypenexi Trasfer Prolecol 缚 富 ， 同 目标 计算 机 过 行 通 俯 的 协议 
[E 第 一 部 分 —MmhiEROECLISEMWN, fite xHiUattt. BRMaR 
B WUHTMLSUIpREASRONE. MENIRE NELER 
[E po1z (一 》 Jc TRRBINIENT 
west RUETTPOU EUR REOR ERE HEN 
E} D02Z Weum — SWeRTHIKRUAN 
=] * 02 开发 Web 应 用 程 cot Comas Gascw 关 laerfice 的 业主。 史册 应 用 程序 构成 的 一 名 方式 
序 上 六 的 流 稚 可 以 用 图 2-1 表 示 。 


=HE] E 了 解 Web 应 gc ian 
E 

































































ZAAPA Ca 
E 02.01.01 什么 是 me ERFAN m 
Web 应 用 程序 
[E] 02.01.02 Web 应 
用 程序 与 桌面 应 
用 程序 的 不 同 
[E] 02.01.03 Web® 内容 
用 程序 的 机 制 @ Web 应 用 程序 与 CGI 
EHE] 02.02 ”Web 应 用 程 CGI 是 Web 酸 务 器 执行 Web 应 用 程序 的 一 种 形式 。Web 服 务 秋 通过 执行 CQGI 程 序 
发 的 事前 准备 (CGI 竹本 )， 将 CGI 程 序 的 标 桨 输出 的 内 容 直接 通过 HTTP 人 协议 返回 。 最 简单 的 CGI 
程序 是 适 过 控制 全 冶 商 仅仅 显示 的 一 中 文字 而 已 。 在 Python 的 标准 模块 工具 中 ,有 





E 02.02.01 关于 
Flask 


[E] 02.02.02 Flask) . 
02.1 


7.13 Sphinx 输出 的 PDF 


7.3.4 通过 结构 化 ， 文 档 可 分 成 几 个 文件 来 与 











程序 员 在 与 程序 时 不 会 将 所 有 代码 都 写 在 同一 个 文件 里 。 
我 们 ， 这 样 做 是 非 稼 不 明智 的 。 源 人 码 要 以 概念 或 目的 为 单位 分 


iid 








— IMKCGIHTTPServerd) CGIBE HS] EAW 4-32: 67. T RT TOR CES ME 
一 下 。 


help-py 
ier rej eid QU thon 
eren nen -Type: text/plaii 
print * 
print adis cci!" 
mid EA RIPythonfizi;, SbETEISONGDERE FRU TTC 
如 果 用 CGIHTTPServer 执 行 OGI 的 话 , 8:39:46 i3 3c (LA — T1 cgi-bin B 3 
下 ,我 们 可 以 建立 该 目录 ， 将 hellopy 放 入 其 中 。 文 件 放 到 指定 位 置 后 ， 通 过 python 
命令 使 用 -m 千 项 执行 CGIHTTPServer 模 块 。 
i-bin 
sm coi-bin, m 
envie WI i 8.0.0. Ü Pt seee . 
该 命令 执行 后 . fefhiT SIS D ( 这 里 是 VzmaiBox 上 的 Ubuntu ) 就 会 打开 8000 
的 狗 口 进行 者 昕 ， 等 竺 请 求 的 到 来 ， 如 此 一 来 Web 服 务 器 便 正式 启 矿 了 。 停 止 Web 
R3 2805750 RE Fro. 
本 地 环境 ( REHosti SE 5$ ) PAWR EMERE HALRA, 
须 通 过 SSH 连 接 建立 一 个 隘 道 。 如 有 果 需 要 建立 一 个 本 地 的 3000 山 口 和 VirtalBos 上 的 
3000 测 口 的 角道 可 以 使 用 下 而 的 命令 。 


Basse a socom oin 
$ zzh -p 2222 -L 8600:127.0.0.1:8800 bpbockg127.0.8.1 


Ld ddr4- BUE P iE Ko EA EbpbokNM P, RIDE ME 
SSH. SSHM9.£ X- MH ACTVUREREKB. 


3832 Weba 838 Ufo] 46 iE hgtp:/127 0.0.1-8000/cgi-binhello py, SETT UR EMA 
器 中 吕 示 Halo CGI 这样 的 信息 。 
12700. 4 3t AREA 3x RE. 


这 个 CGI 得 岸 的 例子 是 使 用 Python 编写 的 ， 如 果 单 从 CGI 的 输出 来 看 ， 和 只 体 编 
程 语 育 的 实现 是 无 关 的 。 


因为 历史 和 长 期 以 来 的 经 验 告诉 
让 割 成 多 个 文件 ， 在 目录 中 进行 分 











个 做 法 对 于 文档 同样 有 效 。 人 有 
godere 比如 LIST 7.13 这 个 例子 就 能 让 人 一 眼看 出 文档 的 结构 ， 非 常 清晰 。 


© LIST7.13 文档 目录 结构 示例 
文档 / 


+-- index.txt 
9 | EE 
+-- index.txt 


| +-- project-goal.txt 
| +-- member-and-structure.txt 


+-- phasel-schedule.txt 


+-- 设计 / 
| +-- index.txt 
| +-- middleware-versions.txt 


| +-- framework-comparision.txt 
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| +-- gerver-structures.txt 
| +-- components-and-interfaces.txt 
+-- 开发 / 
| +-- index.txt 
| +-- repository.txt 
| +-- coding-rule.txt 
| +-- develop-environment.txt 
| +-- release-packaging.txt 
+-- 参考 手册 / 
| +-- index.txt 
| +-- install-and-setup.txt 
| +=- class-and-functions.txt 
| pr inenc e EE 
+-- 会 议 记 录 / 
+-- index.txt 


+-- 20150201-meeting.txt 
+-- 20150208-meeting.txt 
+-- 20150215-meeting.txt 


这 样 分 类 之 后 ， 我 们 写 文档 时 的 注意 力 束 会 转移 到 以 下 几 项 上 。 相 较 于 在 单一 文件 中 编写 
文档 ， 这 样 能 更 加 轻松 地 整理 文档 内 容 。 











。 根据 分 类 或 文件 名 调整 该 文件 涉及 内 容 的 范围 
。 文件 内 容 或 文章 量 达到 一 定 规 梗 后， 重新 整理 内 容 、 分 割 文件 
。 文件 达到 一 定数 量 后 ， 将 同一 分 类 的 文件 归 入 一 个 子 目 录 











如 上 面 例子 所 示 ，Sphinx 可 以 借助 文件 分 割 以 及 目录 分 类 来 构筑 文档 。 这 些 分 割 开 的 文 
件 会 在 使 用 Sphinx 构建 时 通过 链接 等 方式 添加 关联 ， 并 采用 适合 HTML, PDF 等 格式 的 形式 
输出 。 

至 于 输出 之 后 的 效果 ， 完 全 可 以 交 给 HTML 或 PDF 等 输出 算法 来 处 理 。 写 文档 的 人 只 需 关 
心 文档 结构 是 否 符合 逻辑 ， 链 接 数 量 是 否 恰到好处 等 。 也 就 是 说 ， 我 们 能 完全 以 逻辑 思考 为 中 
心 来 编辑 文档 ， 不 必 去 想 多 余 的 事 。 























7.3.5 ”能 用 Mercurial 等 轻松 实现 版 本 管理 
Sphinx 的 文档 由 多 个 日 录 下 的 多 个 纯 文 本 文件 共同 构成 。 图 片 文 件 也 和 文本 文件 一 样 保 存 
在 目录 中 。 在 这 种 结构 下 ， 我 们 能 以 极 细 的 粒度 进行 版 本 管理 ， 而 且 即 便 出 现 多 人 同时 编辑 文 
档 的 情况 ， 各 个 变更 之 间 也 不 会 发 生 冲 突 (图 7.14 )。 
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女工 作 目 录 +*+ 

default tp A 网 11. 1-2. 1-3 Zhang San — publi 101.. tip 
au default f$2utx3EHTESL 
ault $ review 合并 

第 10 章 前 2 小 广 

完成 第 1 章 
ew review 创建 帘 校 分支 

加 入 引言 部 分 





o e 9 o » wel: 
+ 











网 | sss 过 泪 文 本 ess .,2 Q 分 支 : review 复制 提交 说 明 EA O 

m : 父 版 本 : 1 (B46549febc43) 创建 审 校 分 支 
一 AEE 。 9m AND |S RRR berrou IHRE MA] 
[V] M 00rst rst 4 














NL] 





* "m 
tE +e a oos 





20 
21 IF?DAÍFIEDS chg33512 , IPEDHO BLA 2 ERES. (OBeProudtiñ T 8B T: 
22 | 


E 























7.14 用 Mercurial 管理 Sphinx 文档 


7.3.6 API 参考 手册 与 程序 的 管理 一 体 化 


作为 开发 者 ， 我 们 有 时 候 会 目 己 写 API， 有 时 候 又 会 拿 现成 的 API 来 用 。 理 想 的 情况 是 写 
好 API 的 同时 就 能 做 好 API 参考 手 册 ， 但 如 果 是 没有 人 读 的 东西 ， 做 出 来 也 只 是 白费 功夫 。 所 
以 什么 时 候 该 做 什么 东西 ， 要 仔细 结合 重要 性 进行 考量 。 

进行 Python 开发 时 ， 只 要 docstring 用 得 好 ， 完 全 可 以 解决 这 一 问题 。docstring 指 的 是 写 在 
Python 模块 、 类 、 羡 数 最 开头 的 字符 串 对 象 。 比 如 ， 我 们 会 用 docstring 在 函数 的 开头 像 LIST 
7.14 这 样 描 述 文档 。 























© LIST 7.14 path.py 


4 -*- coding: utf-8 -*- 


der ceomnonp5retscgathe us) 
返回 路 径 的 “~path list`” 中 最 长 的 公共 前 级 
( 依次 判断 路 径 名 的 每 一 个 字符 ) 


> COmMMOonprertix | sr buimpyt eloe Au p yt hore) 
uu. 
>>> cCommonprefix(['/usr/bin/python']) 


'/usr/bin/python' 
WR “path 1ist`~” 为 空 ， 则 返回 空 字符 呆 “ 


>>> commonprefix([]) 
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请 注意 ， 由 于 每 次 只 判断 一 个 字符 ， 
所 以 可 能 返回 非法 路 径 


>>> commonprefix(['/usr/local/bin/python', '/usr/local/bin/pylint']) 
1 /fusr/local/bin/ipy' 
LE DOE path ligt; recumrm 1! 
sil = min (parn List) 
s2 = max(path list) 
for i, c in enumerate (s1): 
we @ la Dean: 
recura sdb] 


en sii 


All LIST 7.15 TR, DART ACE EET] RRO RT EAE SZ EG HP H. 


加 LIST 7.15. 函数 文档 的 引用 
>>> help(path.commonprefix) 


Help on function commonprefix in module path: 


commonprefix (path list): 
Eme "path list^" e 2t 808 
( 依次 判断 路 径 名 的 每 一 个 字符 ) 


>>> commonprefix(['/usr/bin/python', '/usr/local/bin/python']) 
uta cor 
>>> commonprefix(['/usr/bin/python']) 
ı deas As YE 
- (mig ga ) - 


Python 还 拥有 doctest 功能 ， 它 能 够 识别 出 在 docstring 中 描述 的 ， 也 就 是 和 交互 模式 显示 信 
县 相同 的 部 分 并 进行 测试 。 进 行 doctest 的 最 简单 的 方法 就 是 执行 LIST 7.16 中 的 命令 。 








加 LIST 7.16 doctest 


S python mooetest Arap 


4 tests in 2 items. 
4 passed and 0 failed. 


Test passed. 


QUEE—ORK, RAZOA UT ARARA BELA IAE MmT o 237b. RITE AHO H 
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将 docstring fA Sphinx 文档 。 植 人 时 要 用 到 sphinx.ext.autodoc 扩展 ， 具 体 描述 如 下 (LIST 
7.17、LIST 7.18 )。 


© LIST 7.17 conf.py 


sys.path.insert(0, ' [path.py MEE rRNR) 


extensions = ['sphinx.ext.autodoc',] 


© LIST 7.18 path.rst 


caubpotunctuion:-.path-commonpestux 


然后 我 们 就 能 够 得 到 图 7.15 中 的 输出 结 来 了 。 





SW-Project 1.0 文档 > 










AutoDoc 范 例 


path. commonprefix(path list) 
返回 路 径 的 €" list 中 最 长 的 公共 前 缀 “依次 判断 路 径 名 的 每 一 个 字符 ) 。 


»»» commonprefix(['/usr/bin/python', '/usr/local/bin/python']) 
‘Ju , 

»»» commonprefix(['/usr/bin/python']) 

' /usr/bin/python* 

输入 相关 的 术语 ， 模 块 ， 类 或 者 函数 iae i . 

名 称 进行 搜索 如 果 `path_list 为 空 ， 则 返回 空 字符 串 〈”) 。 


>>> commonprefix([]) 
请 注意 ， 由 于 每 次 只 判断 一 个 字符 ， 所 以 可 能 返回 非法 路 径 。 


onprefix pum /usr/local/bin/python', '/usr/local/bin/pylint']) 
Ju e al/bin 
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加 版 权 所 有 2016, BeProud. H Sphinx 1.3 创建 。 


7.15 用 sphinx.ext.autodoc 将 docstring 植 入 Sphinx 文档 


可 见 ， 只 要 API 的 实现 及 其 相关 文档 保持 在 可 测试 状态 ， 并 保证 其 能 日 动 植 入 Sphinx 文档 之 
中 ， 许 多 问题 就 迎 思 而 解 。 为 外， 如 测试 驱动 开发 一 样 ， 将 介绍 API 使 用 方法 的 文档 兼 测试 
写 在 实现 API 之 前 ， 这 既 能 让 人 们 对 该 API 的 使 用 有 一 个 更 明确 的 认识 ， 也 能 给 开发 市 来 帮助 。 














| 


7.3.7 通过 Web 浏览 器 共享 


文档 内 和 背包 含 开 发 规则 或 API 参考 手册 等 内 容 。 诈 成 员 能 在 Web 上 浏览 到 这 些 信 息 会 市 
来 许多 好 处 。 

当 我 们 想 和 其 他 开发 者 共享 某 个 文档 ， 进 而 展开 讨论 或 交流 时 ， 如 有 能 通过 URL 指定 该 文档 ， 
那 将 让 共 吾 变 得 非常 方便 。 而 且 这 样 做 不 需要 在 邮件 上 挂 附件 ， 能 避免 出 n 的 文档 副本 。 

Sphinx 用 起 来 最 方便 的 输出 格式 就 是 HTML。 我 们 可 以 设置 一 个 机 制 ， 在 Mercurial 的 版 本 
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và 
J 
Wy 
d} 





管理 之 下 提交 Sphinx 源码 时 ， 用 Jenkins 目 动 将 其 构建 成 HIML， 这 样 一 来 就 能 随时 在 Web 上 
看 到 最 新 的 文 要 了 。 与 Jenkins 的 关联 我 们 将 在 第 10 ERTEM T Ho 


7.3.8 导入 Sphinx 后 仍 存在 的 问题 


前 面 我 们 了 解 了 Sphinx 作为 文档 编辑 工具 的 一 面 ， 但 有 些 问题 并 不 是 叶 入 Sphinx 就 能 解决 
的 。 为 外 ， 对 于 非 程 序 员 或 非 拉 术 人 员 来 说 ，Sphinx 的 茶 些 优点 反而 会 变 成 缺点 。 
所 以 ， 我 们 这 里 要 探讨 导入 Sphinx 无 法 解决 的 问题 以 及 导入 后 新 增 的 问题 。 








€ 与 有 用 的 文档 
我 们 在 “让 人 愿意 写 文档 并 能 轻松 写 文 档 的 条 件 ” 中 提 到 了 “ 写 有 用 的 文档 ”这 一 条 。 可 
惜 的 是 ， 仅 导入 Sphinx 并 不 能 解决 这 一 问题 。 在 7.4 市 ， 我 们 将 学 习 如 何 写 有 用 的 文档 。 








€) 审查 需要 多 化 心思 

许多 文字 处 理 软件 都 配备 了 审查 或 审 校 的 功能 ， 但 Sphinx 中 并 没有 这 类 功能 。 所 以 在 进行 
审查 校对 、 反 馈 校 对 内 容 等 工作 时 ， 需 要 额外 花 些 心思 才 行 。 

Sphinx 中 有 用 来 记录 todo 的 扩展 表示 法 。 使 用 这 个 功能 前 ， 先 要 在 conf.py 中 作 如 下 设置 
( LIST 7.19 )。 





回 LIST 7.19 conf.py 


extensions = ['sphinx.ext.todo',] 


toco include todos = True 


然后 像 LIST 7.20 这 样 在 文档 中 描述 审查 校对 的 内 容 。 





Ej LIST 7.20 É todo 指令 中 描述 校对 内 容 
今日 议程 


NR 
2. 面向 开发 者 的 程序 库 的 开发 情况 
3. O HERT AT 


. todo:: (sato) 缺少 *x 事务 联络 **， 请 添加 。 


如 果 想 获取 todo 的 一 览 表 ， 需 要 在 文档 的 任意 位 置 加 一 行 .. todolist:: 然后 make html; 





sphinx.ext.todo - Support for todo items 


http://www.sphinx-doc.org/en/stable/ext/todo.html 
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€ 部 分 人 只 会 在 WYSIWYG 编辑 器 上 写 文档 

前 面 也 说 了 ，Sphinx 的 信息 与 视图 是 分 离 的 ， 所 以 我 们 能 集中 精力 去 编写 文章 ， 不 必 为 装 
饰 等 外 观 方面 的 问题 分 心 。 但 是 对 于 一 部 分 人 而 言 ， 不 能 把 握 输 出 效果 就 写 不 下 去 文章 。 这 一 
类 人 会 觉得 没有 WYSIWYG 编辑 希 的 Sphinx 很 难 用 。 这 个 问题 暂时 还 没有 很 好 的 解决 方法 。 














e 输出 PDF 需要 搭建 相应 的 环境 

虽然 Sphinx 文 持 多 种 输出 格式 ,但 仪 有 它 本 里 时 ， 是 不 能 输出 PDF 的 。 输 出 PDF 有 两 种 
方法 (经 由 LaTeX 和 使 用 reportlab 扩展 )。 这 两 种 方法 各 有 特点 ， 其 中 经 由 LaTeX 的 输出 更 加 
直观 。 

关于 用 Sphinx 输出 PDF 的 方法 , http://www.sphinx-doc.org/en/stable/ 
index.html 网 站 上 介绍 了 相关 的 导入 流程 以 及 使 用 方法 。 些 外， 该 网 站 上 还 介绍 了 将 Sphinx 
文档 经 由 LaTeX 输出 成 PDF 的 方法 。 








用 Sphinx 生成 PDF 文件 
http://www.sphinx-doc.org/en/stable/tutorial.html?highlight-pdf 





7.4 文档 集 的 创建 与 使 用 





各 位 在 号 文档 时 部 注意 了 哪些 点 呢 ?” 男 外 ， 要 想 号 出 一 篇 有 用 的 文档 ， 有 了 哪些 点 需要 注意 呢 ? 

文档 是 有 读者 的 。 如 玉 在 写 文档 时 没有 考虑 读者 ， 那 我 们 的 意识 就 会 仿 到 “应 该 加 入 哪些 
信息 ” “应 该 与 到 哪 种 程度 ”上 ， 绪 采 就 是 相关 信息 越 涩 越 多 ， 最 后 却 筷 了 原本 要 表达 的 信息 ， 
导致 文档 不 能 达到 原 定 的 目的 。 能 让 该 者 党 得 是 好 文档 的 文档 ， 必 然 考 虑 了 “该 者 是 谁 ”以 及 
“ 雯 样 写 能 让 读者 看 得 更 明白 ”等 问题 ， 确 保 为 读者 提供 了 充足 且 有 用 的 内 容 。 

文档 的 目标 读者 、 内 容 、 座 度 等 问题 ， 可 以 拿 过 去 项 目的 文档 来 参考 。 我 们 知道 , “文档 的 
写法 ”“ 厂 本 库 的 用 法 ”“ 项 目的 推进 放 法 ”这 类 东西 都 是 可 以 重复 利用 的 。 同 样 直 理 ， 一 个 项 
日 文档 的 许多 元 系 完 全 可 以 拿 到 为 一 个 文档 中 重复 利用 。 



































7.4.1 什么 是 文档 集 


如 今 有 一 种 思路 ， 就 是 为 了 重复 利用 文档 而 将 文档 模板 化 ， 然后 构建 成 文档 集 ( Documentation 
Portfolio ), (Python 高 级 编程 》 一 书 将 文档 集 称 为 文档 工件 集 ， 并 作出 如 下 定义 。 


© 原 书 名 为 Expert Python Programming, Tarek Ziadé 著 ， 姚 军 等 译 ， 人 民 邮 电 出 版 社 ，2010 年 1 月 。 
译 者 注 
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从 作者 的 角度 ， 这 可 以 通过 拥有 一 组 可 复 用 的 模板 和 描述 如 何 、 何 时 在 项 目 中 使 
用 这 些 模板 的 指南 来 完成 ， 它 被 称 为 文档 工件 集 。 
也 就 是 说 ， 一 个 文档 集 由 以 下 内 容 构 成 。 


e 文档 模板 集 ( 规则 、 流 程 、 会 议 记 录 、 设 计 等 ) 
e 使 用 文档 模板 的 导航 ( 何 时 用 、 坟 样 用 等 说 明 ) 





7.4.2 项目 所 需 文档 的 一 多 表 


Scoot Ambler AJ (PEER: 极限 编程 和 统一 过 程 的 有 效 实 践 》 一 书 中 有 文档 集 的 相关 信 
县 ， 可 供 各 位 参 邯 。 他 在 书 中 提 到 了 项 目 所 需 的 文档 一 览 表 ， 同 时 举 了 例 了 于， 现 整 理 如 下 。 














e 文档 一 宽 表 ( 精 选 ) 
。 协 以 模型 : 天 于 系统 的 技术 性 界面 
。 设计 上 的 已 确定 事项 : 设计 和 架构 方面 的 重要 决定 的 记录 
。 对 上 级 的 概要 说 明 : 系统 构想 、 需 求 、 当 前 的 预 佑 、 风 险 、 人 员 计 划 、 日 程 安排 
。 使 用 文档 : 使 用 时 所 需 信息 、 流 程 、 环 境 的 概述 
。 项 目 概 要 : 开发 时 所 需 信息 、 流 程 、 环 境 的 概述 
。 需 求 文书 : 定义 系统 需要 完成 的 目标 
。 文 持 文 档 : 给 技术 文 持 独 的 培训 和 资料、 问题 排查 、 维 护 团 队 的 联络 方式 一 览 表 等 
。 系 统 文档 :系统 概要 、 构 染 、 需 求 事项 等 的 概要 
。 用 户 文档 : 使 用 说 明 书 、 培 训 资 料 等 























敏捷 建 模 的 文档 列表 基本 网 多 了 所 有 必 备 信息 。 但 这 仍 存在 一 些 问题 ， 比 如 从 完全 没有 文 
档 的 状态 起 步 时 ， 我 们 很 难 一 次 性 将 这 些 文 档 全 写 出 来 。 所 以 第 一 步 ， 可 以 先 处 理 目 身 团 队 或 
组 织 所 知 的 部 分 ,或 者 是 以 过 去 的 文档 为 基础 ， 将 文档 的 目的 抽 选 出 来 进行 类 似 上 述 分 类 ， 进 
而 模板 化 。 最 终 我 们 将 构筑 出 适用 于 目 己 或 团队 的 文档 集 ， 供 我 们 在 今后 的 项 目 中 加 以 利用 。 
接 下 来 ， 我 们 将 根据 目标 读者 的 类 型 分 别 了 解 一 下 文档 集 。 





7.4.3 面 回 项 目 组 长 、 经 理 

普通 程序 员 很 难 想象 项 目 组 长 、 经 理 们 想 要 的 信息 ， 所 以 更 谈 不 上 将 它们 写 人 文档 。 这 里 
最 好 的 办 法 就 是 向 项 目 组 长 、 经 理 询问 具体 想 要 的 信息 。 各 位 不 妨 以 本 节 所 讲 的 内 容 为 基础 ， 
跟 项 目 组 长 、 经 理 探讨 一 下 访问 客户 之 前 应 该 掌握 哪些 信息 ， 应 该 将 哪些 东西 落实 在 文档 中 。 
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© 项 目的 目标 ( 终点 ) 

在 项 目 目标 中 ， 我 们 要 写 出 “用 户 导 和 我 们 即将 开发 的 系统 后 能 获取 何 种 收益 ” “与 以 往 相 
比 有 哪些 改善 ”之 类 的 信息 ， 而 技术 和 系统 方面 的 目标 则 不 必 在 此 太 过 重视 。 当 然 ， 有 些 项 目 
KAMEN T HFE Python 程序 库 ， 这 时 拉 术 和 系统 方面 的 目标 就 成 了 必须 写 和 人 日 标的 事项 。 不 
过 ， 这 种 情况 也 必须 写 清楚 为 什么 要 开发 这 个 东西 。 

项 目的 目标 (终点 ) 目 然 应 该 跟 所 有 参与 项 目的 成 员 共 部 ， 但 意外 的 是 ， 这 一 点 在 现实 中 
贯彻 得 并 不 好 。 即 便 团 队 中 茶 些 成 员 只 负责 禹 代码 ， 我 们 也 应 该 把 目的 共 至 给 整个 团队 。 更 何 
况 ， 在 文档 中 写 明 目标 对 项 目 组 长 本 吴 也 有 帮助 。 或 许 尚 不 玖 悉 项 目 运 介 的 组 长 会 党 得 “目标 
会 经 第 跟着 客户 的 要 求 变 "， 但 实际 看 来 ,目标 破 正 改变 的 项 目 并 不 多 。 我 们 不 光 要 询问 客户 的 
要 求 ， 还 要 将 日 标 沙 实 到 字面 上 ， 然 后 跟 客户 以 及 项 目 组 成 员 共 于 出来， 这样 才能 给 项 目 创 造 
出 一 个 主干 ， 使 开发 有 条 不 蔡 。 如 来 这 一 点 上 搞 不 清楚 ， 那 这 个 项 目 从 头 至 尾 都 不 会 稳定 ， 难 
免 发 后 差错 ， 甚 至 会 导致 返工 。 


















































@ 体制 

在 项 目的 体制 中 ， 要 写 明 各 个 参与 者 (团队 ) 的 职务 ， 使 成 员 们 清楚 目 己 在 项 目 中 的 定位 。 
只 务 不 能 只 写 名 称 ， 还 要 写 明 各 职务 需要 做 的 工作 ， 让 人 明日 每 个 职务 该 负 起 哪些 责任 。 如 采 
只 写 一 个 “ 主 程序 员 ”， 那 么 任 谁 午 搞 不 清楚 这 个 职务 应 该 负责 什么 。 这 部 分 虽然 不 必 写 得 很 严 
密 ， 但 必须 让 每 个 职务 对 应 的 人 员 清 楚 上 日 己 的 职责 范围 ， 不然 项 目 开 发 的 过 程 中 必定 出 现 大 问 
如 。 为 外 ， 菏 些 职务 或 团队 的 人 数 需 要 根据 参与 时 期 进行 调整 ， 这 类 信息 最 好 也 写 进来 。 






































需求 

需求 是 很 重要 的 。 在 项 目 开始 之 前 ， 需 求 底 已 经 豚 胱 地 存在 于 客户 脑 中 了 。 我 们 的 设计 与 
开发 全 都 要 以 需求 为 准 。 在 开发 过 程 中 ， 需 求 是 考察 系统 完成 度 的 指标 ， 如 采 需 求 不 明确 ， 我 
们 完全 无 法 判断 系统 的 发 展 方 癌 是否 正确 ， 也 无 法 考察 开发 到 了 哪里 。 到 了 运 介 阶段， 我 们 也 
需要 参考 需求 来 了 解 系统 的 概念 或 衡量 业务 变更 的 影 啊 。 

在 定义 需求 时 ,一 般 要 将 需要 哪些 功能 、 需 要 怎样 运营 、 需 要 运行 性 能 达到 何 种 程度 等 信 
县 逐条 列 出 或 者 汇总 成 表 。 





























@ 日 程 、 咨 询 项 目 表 

对 实现 需求 的 日 程 进行 描述 。 能 左右 日 程 的 因素 有 很 多 ， 比 如 客户 的 要 求 、 当 前 可 处 理 的 
汇 围 、 能 影响 到 日 程 的 外 部 因 系 ， 等 等 。 在 初期 阶段 ， 日 程 常会 受 各 种 因 系 影响 而 变化 ， 所 以 
要 定期 重新 审视 并 做 好 记录 。 

除 此 之 外 还 有 咨询 项 目 表 ， 用 来 与 客户 协商 尚 不 明确 的 事宜 。 
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7.4.4 ”面向 设计 者 


面 回 设计 者 的 文档 需要 对 构架 和 概念 多 加 描述 ， 但 随 春 时间 推 移 ， 选 择 该 设计 、 基 础 结构 、 
开发 语言 的 理由 会 显得 越 来 越 重要 ， 所 以 这 些 也 要 写 在 文档 中 。 为 外 ， 在 OS 和 开发 语言 方面 ， 
最 好 也 写 上 选择 该 版 本 的 理由 。 以 Python 为 例 ， 假 设 我 们 选用 了 较 旧 的 2.5 版 ， 理 由 可 能 是 只 
有 这 个 版 本 提供 了 我 们 用 作 基 础 结构 的 服务 ， 也 可 能 是 当时 没有 发 布 新 版 本 ， 或 者 是 OS 的 程 
序 包 管 理 中 没有 新 版 本 ， 又 或 者 是 公司 的 方针 规定 不 采用 最 初 的 主 版 本 ， 总 之 可 能 的 情况 非 稼 
之 多 。 如 末 文 档 中 没有 对 这 些 情 况 做 记录 ， 一 旦 将 来 要 探讨 版 本 变更 问题 ， 那 将 会 是 一 件 非 稼 
WAS BUR o 

涉及 下 列 各 项 时 ， 请 各 位 务必 记录 选择 的 理由 。 























。OS、 语 言 、 版 本 的 选择 
。 构 架设 计 


。 基 础 设施 设计 


7.4.5 ”面向 开发 者 


在 搭建 开发 环境 方面 ， 我 们 提倡 导入 自动 化 机 制 来 尽量 缩短 流程 ,但 还 是 难免 会 遇 到 无 法 
目 动 化 的 部 分 ,或 者 是 上 自动化 成 本 过 高 的 情况 。 因 此 ， 我 们 应 该 将 流程 尽量 详细 地 记录 下 来 ， 
以 备 不 时 之 需 。 有 些 时 候 ， 流 程 文档 的 记录 会 不 人 够 全 面 ， 比 如 只 写 了 搭建 步骤 却 没 写 构建 选项 ， 
等 等 。 要 知道 ， 流 程 文档 是 写 给 不 乙 这 些 的 人 看 的 ， 所 以 应 该 将 命令 行 要 输入 的 内 容 全 部 网 罗 
进去 。 








NOTE 

能 自动 化 的 地 方 不 能 太 音 冰 成本， 应 当 尽 量 自动 化 ， 从 而 降低 搭建 环境 和 编辑 文档 的 成 本 。 

在 一 些 环境 搭建 流程 尚未 优化 的 项 目 中 ， 单 是 给 一 个 开发 者 搭建 环境 束 可 能 花费 超过 一 周 
的 时 间 。 这 种 情况 下 ， 每 当 遇 到 实现 或 测试 阶段 都 会 消耗 大量 的 人 力 资 源 。 软 件 开 发 项 目 中 的 
证 多 机 制 都 可 以 自动 化 ， 其 中 与 搭建 环境 相关 的 自动 化 最 好 在 项 目 起 步 时 就 准备 好 。 

本 书 将 在 第 9 章 和 第 11 章 中 介绍 自动 化 搭建 环境 的 相关 内 容 。 


7.4.6 ”面向 客户 


面向 客户 的 文档 包括 指导 如 何 使 用 成 品 程序 的 学 习 手 册 ， 以 及 总 结 了 日 常 操作 流程 的 使 用 
H PEE e 
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当然 ， 前 面 讲 到 的 设计 、 开 发 、 搭 建 环 境 等 的 文档 一 般 也 会 交付 给 客户 ， 但 除了 客户 想 目 
己 修 改 程 序 之 外 ， 这 些 文档 的 内 容 都 太 过 星 深 ， 而 且 客 户 无 法 对 内 容 加 以 干涉 。 与 此 相对 ， 使 
用 手册 是 客户 日 弟 会 用 到 的 东西 ， 而 且 客 户 在 给 这 类 文档 的 内 容 提 要 求 时 更 清楚 日 己 想 要 什么 。 

是 否 需 要 面 问 客户 的 文档 ， 或 者 文档 中 该 有 哪些 内 容 ， 这 虱 和 需要 与 客户 认真 探讨 系统 的 使 
用 情境 之 后 再 决定 。 如 果 定 不 下 来 ， 奢 么 很 可 能 是 客户 日 己 对 系统 没有 一 个 明确 的 设想 。 这 种 
情况 下 ， 客 己 可 能 在 收 到 成 品 后 或 开始 使 用 后 才 发 现 “ 这 中 我 想 要 的 不 一 样 ”。 所 以 为 了 防止 出 
现 这 类 问题 ， 我 们 必须 与 客户 认真 探讨 ， 共 享 成 品 在 开始 运 彰 后 的 情境 ， 编 写 出 所 需 的 文档 。 









































7.5 小结 





本 章 对 “什么 样 的 环境 便于 开发 者 写 文档 ”进行 了 整理 ， 并 以 Sphinx 为 例 介绍 了 实现 此 类 
环境 的 方法 。 

我 们 无 法 保证 大 程序 从 一 开始 就 能 被 正确 实现 ， 同 样 道理 ， 我 们 也 无 法 你 证 大 文档 从 一 开 
始 就 能 有 一 个 正 硝 的 结构 。Sphinx 这 类 结构 便于 文档 阶段 性 成 长 ， 它 能 防止 我 们 在 写 文档 上 浪 
充 荔 动力 ， 同 时 也 能 作为 指 四 标 ， 引 导 我 们 最 终 完 成 一 份 恰到好处 的 文档 。 

另外 ， 对 于 “ 写 有 用 的 文档 ”这 一 无 法 用 工具 解决 的 问题 ， 各 位 可 以 运用 文档 集 来 弥补 。 
将 已 有 文 梢 的 结构 和 构造 升华 为 文档 集 来 重复 利用 ， 不 但 能 逐 靖 提高 文档 的 品质 ， 还 能 有 效 降 
低 文档 编写 的 成 本 。 
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Python 上 手 容 易 ， 编 程 者 可 以 很 快 投入 到 应 用 的 开发 之 中 。 但 这 里 不 能 操之过急 。 在 动手 
之 前 ， 各 位 要 先 问 一 问 上 自己 : 理解 接 下 来 要 做 的 东西 了 吗 ? 知道 该 怎么 做 了 吗 ? 

没 错 ， 痪 代码 前 还 有 一 个 必 经 的 步 骆 ， 那 就 是 设计 。 

为 外 ， 病 完 代 码 之 后 还 少不了 测试 。 如 今 ， 在 极限 编程 等 敏捷 开发 方法 的 影响 下 ， 人 们 对 
测试 的 认识 正在 从 “ 麻 烦 ” 逐 渐 问 厦 “主导 开发 的 步 怠 ” 转 受 。 

从 某 种 意义 上 讲 ， 设 计 是 对 测试 的 一 种 输入 ， 因 为 我 们 只 能 在 测试 的 过 程 中 检验 目 己 明确 
设计 出 来 的 东西 。 另 外 ， 吻 于 测试 的 设计 还 能 让 源码 维护 省 力 不 少 。 为 了 让 测试 能 够 立 秆 见 影 ， 
我 们 选择 将 功能 分 割 到 模块 之 中 进行 开发 。 

本 章 会 回 各 位 介绍 将 功能 分 割 到 各 个 模块 的 设计 方法 、 测 试 手法 以 及 如 何 根据 测试 结 来 改 


iunt. 

















8.1 ”模块 分 割 设 计 





应 用 是 由 功能 集合 而 成 的 。 功 能 则 要 通过 函数 、 对 和 象 等 的 相互 作用 来 实现 。 在 Python 中 ， 
函数 、 类 等 (以 下 统称 为 组 件 ) 整合 在 模块 里 ， 模 块 又 整合 在 程序 包 里 。 设 计 的 第 一 步 是 设计 
功能 ， 然 后 才 轮 到 实现 功能 的 各 个 组 件 。 





8.1.1 功能 设计 

在 功能 设计 阶段 ， 我 们 要 敲定 即将 开发 的 应 用 包含 哪些 功能 ， 明 确 各 功能 的 输入 输出 。 

从 应 用 的 角度 看 ， 输 入 输出 不 仅 包括 用 户 能 看 到 的 这 部 分 ， 还 涵盖 了 与 外 部 相关 系统 的 接 
口 、 向 数据 库 保存 的 数据 等 。 

首先 我 们 要 给 功能 写 出 一 个 方案 。 所 谓 方案 ， 就 是 描述 用 户 在 使 用 功能 时 会 与 系统 进行 何 
种 交互 的 文本 。 我 们 要 通过 这 一 步 明确 用 户 向 系统 输入 的 内 容 ， 以 及 系统 该 向 用 户 显 示 的 内 容 。 

将 方案 所 示 的 整个 流程 画 成 图 ， 即 为 页 面 迁 移 图 。 这 里 要 写 下 各 个 页 面 的 功能 。 作 为 一 款 
Web 应 用 ， 应 当 包 含 下 面 几 项 。 











e URL 
e HTTP 方法 
e 安全 (登录 、 权 限 等 ) 
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。 输入 
。 用 户 输入 
。 从 数据 库 或 文件 读 取 
。 外 部 系统 发 来 的 内 容 
e 输出 
。 页 面 输出 
。 问 数据 库 或 文件 写 和 人 
。 外 部 系统 的 调用 


男 外 ， 要 明确 输入 和 输出 的 对 应 关系。 连接 输入 与 输出 是 功能 的 职责 。 在 功能 测试 中 ， 我 
们 要 查看 的 也 是 这 些 输入 和 输出 。 

通过 功能 设计 ， 我 们 确定 了 即将 开发 的 应 用 应 当 脏 样 运作 。 做 完了 这 一 步 ， 接 下 来 就 是 设 
计 “ 如 何 实现 这 些 功能 ”。 简 单 的 功能 通 稼 可 以 一 步 到 位 ， 但 在 实际 开发 中 ， 绝 大 部 分 功能 要 么 
复杂 ， 要 人 么 必须 与 多 个 功能 协同 工作 。 对 付 复杂 的 功能 时 切忌 强求 一 步 到 位 ， 最 好 将 其 视 为 多 
个 部 分 (组件 ) 的 组 合 。 将 复杂 功能 分 割 成 组 件 的 好 处 在 于 可 以 重复 使 用 同一 组 件 来 完成 相同 
的 工作 ， 从 而 有 效 避 锡 应 用 内 的 黎 眉 。 

下 面 ， 我 们 将 对 构成 Web 应 用 的 组 件 进行 了 解 。 随 后 再 来 学 习 如 何 将 功能 分 解 成 组 件 。 








8.1.2 构成 Web 应 用 的 组 件 


将 功能 分 解 成 组 件 需 要 用 到 一 个 指标 ， 我 们 将 这 个 指标 称 为 软件 染 构 。 

Web 应 用 架构 中 最 有 名 的 当 属 MVC (Model View Controller， 模 型 - gk - 控制 项 ) To 
MVC 根据 职责 不 同 对 Web 应 用 的 互动 (应 用 与 用 户 关 联 的 ) 部 分 进行 了 分 割 。M 是 Model, € 
负责 功能 的 主要 逻辑 与 数据 ; V 是 View， 负 责 将 Model 以 用 户 能 理解 的 形式 显示 出 来 ; C 是 
Controller， 它 的 工作 是 根据 用 户 的 输入 将 Model 和 View 联系 起 来 。 

近来 的 Web 应 用 框架 已 经 基本 上 集成 了 Controller 的 功能 。 与 此 同时 ，View 则 更 多 地 被 分 
割 成 HTML 模板 和 显示 逻辑 两 部 分 。 比 如 ，Django、Pyramid 等 框架 就 很 少 需 要 明确 写 出 
Controller， 绝 大 部 分 情况 都 是 Model, View, Template 结构 。 

Model 部 分 在 MVC 中 很 少 被 提 及 。 不 过 ， 当 应 用 不 是 单纯 的 Web+DB 形式 时 ， 其 必然 会 
与 外 部 系统 存在 某 种 协作 。 另 外 ， 虽 然 绝 大 部 分 Model 会 被 永久 保存 ， 但 不 可 否认 有 些 Model 
只 是 为 了 构成 功能 而 存在 的 。 鉴 于 这 些 因素 ， 我们 把 Model 分 成 ApplicationModel 和 
DomainModel 两 类 来 考虑 。DomainModel 是 拥有 持久 (保存 在 文件 或 数据 库 中 ) 状态 的 模型 ， 
而 ApplicationModel 是 用 于 构成 功能 的 模型 ， 虽然 它们 也 能 具有 状态 ,但 这 些 状 态 通 常 不 会 被 
JAMES 
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现在 来 总 结 一 下 构成 Web 应 用 的 组 件 。 由 于 Controller 可 以 完全 交 给 框架 来 处 理 ， 所 以 构 
成 功能 的 组 件 应 如 图 8.1 所 示 。 







| ApplicationModel 


DomainModel ServiceGateway 


数据 库 外 部 服务 
8.1 Web 应 用 构架 


e View 
它 的 工作 就 是 接受 请 求 然后 作出 响应 。 输 入 主要 为 请 求 的 传 值 参数 ， 输 出 则 是 响应 体 。 
它 会 检查 用 户 输入 的 数据 ， 另 外 还 会 加 载 模型 以 及 调用 ApplicationModel。 最 后 ， 它 会 将 
结果 对 象 转换 成 可 以 显示 给 用 户 的 HTML， 生 成 啊 应 体 。 
DomainModel 
拥有 持久 状态 的 对 象 。 大 部 分 情况 下 ， 对 象 的 状态 保存 在 RDBMS 中 。Python 上 能 使 用 的 
O 人 有 映射 工具 〈Object-Relational Mapper ) 以 SQLAlchemy 最 为 有 名 。 男 外 ， 它 还 具有 能 
改变 日 身 状 态 的 业务 人 逻辑 (Business Logic ) 。 
e ApplicationModel 
没有 持久 性 ， 其 状态 是 暂时 的 。 状 态 大 多 只 能 维持 Web 应 用 的 一 次 请 求 ， 或 者 一 定 程 度 
上 完整 的 多 个 页 面 迁 移 期 间 。 它 们 通过 一 般 的 类 、 模 块 中 的 函数 来 实现 。 经 View 调 用 
后 ,执行 其 对 应 的 各 个 DomainModel 内 定义 的 方法 。 它 们 大 多 不 进行 具体 的 人 处理， 只 负 
贡 传 递 处 理 的 流程 。 也 正 是 因为 这 个 ， 它 们 依存 的 模块 通常 较 多 。 
e ServiceGateway 
表示 外 部 服务 。 其 作用 是 为 了 让 Web APIBUfsDERGBDE. WFR. Jn BAI EB 
依存 于 外 部 系统 的 内 容 要 能 够 不 包含 在 Model 和 View 之 中 。 
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e Utility 
它们 大 多 都 很 小 ， 不 具备 状态 ,输入 只 有 荫 数 传 值 参 数 ， 输 出 只 有 返回 值 。 当 然 ， 它 也 
可 以 拥有 多 种 形式 的 输入 ， 以 对 象 状 态 维持 自身 直到 最 终 调用 方法 ， 但 输入 输出 要 符合 
前 面 所 说 的 要 求 ， 在 该 对 象 内 完成 所 有 处 理 。 








一 个 功能 对 应 一 个 View。 

ApplicationMode 和 DomainModel 被 View 调用 。 如 采 DomainModel 只 有 一 种 ， 那 么 程序 将 
通过 View 直接 调用 DomainModel。 当 同时 关联 着 多 个 DomainModel 时 ， 程 序 则 要 通过 View 调 
用 ApplicationModel。 

ServiceGateway 的 作用 就 是 一 个 徐 单 的 封装 ， 它 里 面 不 能 包含 应 用 回 有 的 内 容 。 
ApplicationModel 则 要 使 用 ServiceGateway 进行 应 用 固有 的 处 理 。 








NOTE 
SQLAIchemy 

它 是 连结 对 象 与 RDBMS 的 O/R 映射 工具 库 。 虽 然 SOLAlchemy 并 不 是 Python 唯一 的 映 
OO eo 8), (BIBEEZZ FE BSZIBESEZU-E m, XOBRULIBXIZT So 
f& Pyramid. Flask 等 非 全 栈 式 ( 不 具备 OR 映射 工具 ) 框架 的 说 明 大 多 以 使 用 SQLAIchemy 为 
前 提 ， 这 在 如 今 的 Web+DB 应 用 开发 中 已 经 逐渐 成 为 了 一 条 不 成 文 的 规定 。 


8.1.3 ”组 件 设计 
接 下 来 我 们 把 功能 分 割 到 各 个 组 件 当 中 。 


€ 根据 输入 设计 View 

首先 对 付 输 入 。 作 为 一 蒜 Web 应 用 ,输入 的 主要 来 源 应 该 是 用 户 输入 的 数据 。 除 此 之 外 ， 
已 存在 的 数据 和 从 外 部 系统 获取 的 数据 都 属于 输入 。 

用 户 输 入 的 数据 由 View 接收 。 另 外 ，View 还 负责 和 癌 用 户 传递 数据 。 交 给 模板 的 内 容 要 
由 View 进行 输出 。 在 View 的 内 部 会 调用 ApplicationModel 或 DomainModel， 这 些 Model 也 是 
输入 之 一 。 还 有 ， 由 于 View 没有 状态 可 言 ， 所 以 大 多 数 情 况 以 函数 (以 下 称 View K% ) 形式 
实现 。 














€ 初步 设计 与 View 关联 的 ApplicationModel 
对 View 消 数 而 言 ， 孔 数 传 值 参 数 是 输入 ， 返 回 值 是 输出 。 男 外 ， 它 只 关联 一 种 Model. 
这 一 阶段 我 们 先 不 考虑 DomainModel 的 相关 问题 ， 先 给 每 个 View PR Zi XE X — 71 
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ApplicationModel。View PKI ApplicationModel 建议 根据 功能 名 来 命名 ， 比 如 “{ 功能 名 } 
view, ( 功能 名 1}Model”。 除 此 之 外 ， 还 要 给 ApplicationModel 预先 定义 一 个 方法 ， 名 称 同样 根 
据 功 能 名 来 起 。 


@ DomainModel 的 设计 

接 下 来 定义 DomainModel ( View fll DomainModel 的 定义 可 以 并 行进 行 。 实 际 上 ， 在 设计 
View 之 前 就 可 以 一 定 程 度 上 对 DomainModel 进行 定义 了 )。 由 于 DomainModel 有 状态 ， 所 以 要 
用 类 来 定义 。 

定义 好 DomainModel 的 类 之 后 就 要 考虑 方法 了 。 要 明确 各 个 方法 是 如 何 改变 DomainModel 
的 状态 的 。 这 些 状态 要 定义 成 属性 。 另 外 ， 如 有 条 要 通过 调用 方法 来 改变 其 他 相关 DomainModel 
的 状态 ， 需 要 在 目标 DomainModel 里 定义 方法 ， 然 后 调用 目标 DomainModel 里 的 方法 。 切 记 不 
可 以 直接 改变 其 他 DomainModel 的 状态 。 











图 关联 ApplicationModel 和 DomainModel 
接 下 来 给 ApplicationModel 和 DomainModel 添加 关联 。 在 ApplicationModel 的 方法 中 定义 
需要 调用 的 DomainModel。 然 后 检查 功能 的 输入 输出 是 否 满足 要 求 。 








e 整理 ApplicationModel 

当 ApplicationModel 只 关联 着 一 个 DomainModel bI, 259 ER TZ ApplicationModel, ik 
View 和 直接 调用 DomainModel。 在 ApplicationModel 中 ， 对 旬 Domain 模型 一 致 地 要 整合 成 一 个 
类 。 整 合 好 之 后 需要 立刻 给 类 命名 。 如 采 无 法 确定 类 和 名， 就 尽量 不 要 整合 。 








@ 从 组 件 设计 转 入 实现 
到 这 里 ， 我 们 已 经 将 功能 分 制 到 了 各 个 组 件 之 中 。 接 下 来 就 是 把 它们 向 Python 的 模块 、 程 
序 包 一 步 步 整合 了 。 








8.1.4 模块 与 程序 包 


现在 我 们 根据 目的 把 组 件 整合 成 模块 或 程序 包 。 开 发 Web 应 用 时 ， 要 每 一 个 功能 制作 一 个 
程序 包 ， 功 能 内 的 各 个 组 件 ( View, Model 等 ) 分 别 制 成 模块 。 在 Python 中 ， 各 个 组 件 由 类 和 
KRESKI 
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NOTE 

我 们 来 整理 一 下 Python 的 模块 与 程序 包 

模块 

Python 的 源码 文件 就 是 一 个 个 模块 。 里 面 整合 着 多 个 类 、 函 数 、 变 量 等 内 容 。 虽 然 我 们 可 
以 把 处 理 写 到 模块 内 ， 但 当 我 们 开发 的 应 用 由 多 个 模块 构成 时 ， 最 好 只 让 它 作 为 一 种 范 效 和 次 

集合 体 出 现 。 

程序 包 

整合 在 一 起 的 多 个 模块 。 它 就 是 把 程序 包 内 包含 的 模块 文件 与 __init _.py 整合 到 了 一 个 单 
独 的 目录 下 。 

命名 空间 程序 包 

程序 包 的 一 种 比较 特殊 的 形式 ， 用 来 向 多 个 位 置 安装 相同 名 称 的 程序 包 。 因 为 只 有 在 分 配 
库 文件 的 时 候 才 会 用 到 它 ， 所 以 一 般 应 用 都 与 它 无 缘 。 


e 项 目的 文件 结构 
以 MVC 架构 为 基准 时 ， 项 目的 实际 文件 结构 如 下 所 示 。 


project/ 
S — IMLE OY 
+-- views.py 


+-- models .py 

+-- services/ 

| => IMLE -Y 

| +-- twitter.py 

| +-- twitpic.py 

+-- utils.py 

+-- templates/ 

:i-- tests/ 
== init TS ON 
+== teet models. py 
ao ea e 
+=- CESE SEryVLces py 


+=- CESE UCLLS D7 


O project/. int. .py 
启动 应 用 所 需 的 处 理 都 写 在 这 里 ， 比 如 WSGI 应 用 的 入 口 点 等 。 男 外 ，models 的 导入 、 数 
据 库 连 接 的 初始 化 、 设 置 文件 的 读 取 等 都 在 这 里 进行 。 
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O project/views.py 以 及 project/utils.py 
分 别 实现 View 和 Utility。 


O project/models.py 

实现 DomainModel fll ApplicationModel。 另 外 ,连接 DB 所 需 的 模块 等 也 要 事先 导 和 人 到 
pus 
O project/services/ 

在 存在 多 个 services 时 ， 由 程序 包 进 行 整合 。 





O project/templates/ 
存放 HTML 模板 的 位 置 。 


O project/tests/ 
存放 单元 测试 ( Unit Test ) 的 位 置 。 





另外 ， 当 项 目 规模 非常 大 的 时 候 ， 会 由 多 个 project 合 在 一 起 形成 一 个 网 站 。 比 如 用 户 种 类 
不 同 (终端 用 户 与 服务 提供 方 的 用 户 ) 或 DomainModel 完全 分 离 时 。 


8.2 测试 





完成 设计 之 后 ， 应 该 在 动手 实现 前 先 把 测试 考虑 好 。 因 为 如 琳 没 有 一 个 能 验证 成 品 是 否 符 
合 设计 初衷 的 方法 ， 我 们 根本 无 法 厦 手 去 实现 。 反 过 来 ， 只 要 把 现成 的 测试 摆 在 那里 ， 那 么 我 
们 只 需 以 通过 测试 为 目的 去 编程 即 可 。 

实现 阶段 的 测试 包括 单元 测试 和 功能 单元 测试 。 我 们 应 该 让 其 日 动 化 ， 并 且 时 第 查看 其 结 
果 。 由 于 测试 要 重复 执行 多 次 ， 所 以 必须 保证 其 足够 迅速 ， 并 且 可 以 随时 随地 执行 。 要 满足 
“随时 随地 执行 ”这 一 点 ， 就 意味 着 这 些 测 试 不 能 依赖 于 环境 。 分 离 组 件 可 以 让 不 依赖 于 环境 的 
测试 成 为 可 能 。 

A TEETH RH] Python 中 的 测试 工具 进行 测试 的 手法 ， 以 及 从 测试 中 提出 环境 依赖 的 技巧 。 























8.2.1 测试 的 种 类 

测试 其 实 只 是 一 个 泛泛 的 概念 ， 对 于 不 同 的 对 象 或 观点 ， 其 实施 内 容 都 不 一 样 。 人 们 常 说 
集成 测试 、 单 元 测试 ， 但 究竟 是 集成 了 什么 ， 又 是 以 什么 为 单元 呢 ? 这 里 我 们 以 此 思路 为 基础 ， 
对 其 进一步 细 分 。 
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O 单元 测试 

测试 函数 、 方 法 等 最 小 单元 的 测试 。 这 个 等 级 的 测试 能 明确 看 到 输入 和 输出 ， 所 以 测试 内 
容 往 往 就 是 函数 或 方法 的 设计 方案 本 里。 该 部 分 要 利用 mock 或 dummy， 把 测试 对 象 的 处 理 单 
独 拿 出 来 执行 ， 看 结果 是 否 达 到 预期 。 

















O 组 件 集 成 测试 

这 是 集成 多 个 函数 或 方法 的 输入 输出 的 测试 ， 测 试 时 需要 将 多 个 测试 对 象 组 合 在 一 起 。 由 
单个 测试 对 象 构成 的 流程 已 在 单元 测试 中 测试 完毕 ， 所 以 不 参与 这 一 步 测 试 。 对 象 的 前 后 处 理 
与 单元 测试 一 样 要 使 用 mock 或 dummy。 





O 功能 单元 测试 

测试 用 户 能 看 得 到 的 功能 。 此 时 用 户 的 输入 项 目 以 及 数据 库 等 外 部 系统 为 输入 的 来 源 。 输 
出 则 是 向 用 户 显 示 的 结果 、 回 数据 库 保 存 的 内 容 以 及 对 外 部 系统 的 调用 。 系 统 内 部 不 使 用 mock 
和 dummy， 而 是 全 部 使 用 正式 的 代码 。 不 过 ， 在 对 付 某 些 异 步调 用 之 类 的 难以 和 月 动 测试 的 部 分 
时 ， 需 要 进行 一 定 程 度 的 置换 。 外 部 系统 方面 ， 要 准备 好 虚拟 的 SMTP 服务 器 或 Web API 服务 
器 ， 用 以 执行 应 用 内 的 通信 。 





O 功能 集成 测试 

集成 各 功能 之 间 输 入 输出 的 测试 。 这 里 要 尽 可 能 不 去 直接 查看 数据 库 内 的 数据 ， 比 如 可 以 
用 引用 类 功能 来 显示 更 新 类 功能 生成 的 数据 。 另 外 在 与 外 部 系统 的 联动 方面 ， 要 借助 开发 专用 
的 API 等 模拟 出 正式 运行 时 的 结构 ， 然 后 再 进行 测试 。 这 部 分 测试 要 依赖 于 数据 库 以 及 外 部 服 
务 等 诸多 环境 ， 难 以 自动 执行 ， 所 以 属于 偏 手 动 的 测试 。 




















O 系统 测试 
对 需求 的 测试 。 测 试 成 品 是 否 最 终 满 足 了 所 有 需求 。 在 客户 验收 项 目 时 进行 。 








O 非 功能 测试 
对 性 能 、 安 全 等 非 功 能 方面 进行 的 测试 。 借 助 压 力 测试 软件 进行 正常 /高 峰 /极限 情 况 的 测 
iX, 通过 XSS、CSRF 以 及 注入 式 攻 击 等 模拟 攻击 来 验证 系统 的 安全 性 及 可 徘 性 。 





本 市 ， 我 们 将 束 需 开发 者 主要 负 员 的 单元 测试 、 集 成 测试 以 及 功能 测试 进行 学 习 。 


8.2.2 ”编写 单元 测试 


现在 我 们 来 编写 单元 测试 。Python 的 标准 库 里 有 为 编写 单元 测试 而 准备 的 unittest BEER. 27 
外 ， 执 行 测试 时 建议 使 用 pytest。pytest 是 一 球 能 够 日 动 搜索 并 执行 测试 的 测试 执行 工具 ， 并 且 
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会 输出 详细 的 错误 报告 。 
本 节 将 为 各 位 讲解 如 何 用 unittest 和 pytest 生成 并 执行 单元 测试 。 


@ unittest 模块 

它 是 基于 xunit (YEH unit, sunit 等 ) 的 测试 工具 及 程序 库 。 其 中 主要 使 用 的 是 unittest. 
TestCase 类 。 我 们 定义 一 个 继承 自 它 的 类 ， 然 后 在 其 各 个 方法 中 描述 测试 用 例 ( Test Case )。 测 
试用 例 要 写 在 名 称 以 test 开头 的 方法 中 ， 具 体 如 下 。 

测试 用 例 写 在 名 称 包 含 test 的 方法 中 。 














import unittest 


class TestIt(unittest.TestCase): 


det test seem): 
"num 本 方法 是 一 个 测试 用 例 nau 


GisuE "Erepe eee) 


"num 这 是 另 一 个 测试 用 例 "nn 





另外 ，TestCase ŽEH HIT Ve E XRBEB BUE 28 (Fixture ) 和 用 于 查看 测试 结 采 的 断言 方法 
( Assert Method )。 

FIC EHE HAUT UU a BIS RUE DEAS TEHUTA EE LATE SIR H)SE RH LE unittest 在 执行 
测试 用 例 前 后 会 分 别 调用 各 个 类 的 setUp 和 tearDown 方法 ， 因 此 我 们 可 以 在 这 两 个 方法 内 描述 
执行 测试 所 需 的 环境 设置 LIST 8.1). Python 2.7 之 后 的 unittest 允许 使 用 以 模块 为 单位 的 配置 
希 。 我 们 可 以 把 整个 模块 共通 的 、 不 必 每 次 测试 都 重 置 的 环境 设置 流程 写 在 模块 配置 锅 里 ， 这 
能 够 有 效 削 减 测试 的 执行 时 间 ( LIST 8.2 )。 











B LIST 8.1 各 个 类 的 配置 器 


classcTestrlb(undvbbestrestcase): 


def setUp(self): 
"num T& g& J| i E "num 


def tearDown(self): 


"nan 测试 后 的 环境 清理 "nun 





setUp 在 测试 前 被 调用 ，tearDown 在 测试 后 被 调用 。 
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&3llST8.2 各 个 模块 的 配置 器 


def setUpModule(): 
"nun 搭建 测试 环境 "nun 


def tearDownModule(): 
num 测试 后 的 环境 清 EJE "nnm 


setUpModule 会 在 模块 测试 开始 前 被 调用 一 次 。tearDownModule 
结束 后 被 调用 一 次 。 
Python 在 查看 测试 结果 时 要 使 用 assert 语句 等 断言 。 








a= 1 

bD = 2 

C=a+ bD 

assort icio sg eu-cecque snc 


会 在 整个 模块 的 测试 全 部 





assert MM Erie ER SR (RIER F, HEERE) 不 过 ， 由 于 
assert EAJK H T True, False 的 判断 ， 而 且 信 息 很 多 为 定式 ， 所 以 unittest 的 TestCase 类 


大 多 拥有 目 己 iii 
最 和 常用 的 汤 言 方法 当 属 assertEqual。 刚 才 那 个 例子 改 用 assertEqual 会 


det test Lt exe bar rs 
a-1 
D = 2 
C=a+bD 


self.assertEqual (c, 3) 


€ testfixtures Æ 


会 变 成 下 面 这 样 。 


testfixtures JE (WAAL EZE ) 整合 了 多 种 典型 配置 占 。 里 面包 含 生 成 /删除 临时 目录 、 更 改 
系统 日 期 、 添 加 mock/dummy 等 模块 ， 这 些 模 块 能 帮助 我 们 将 单元 测试 与 环境 分 离开 来 。 
使 用 testfixtures 库 之 前 需要 进行 安装 ， 安 装 步 又 与 通常 的 库 相 同 ( LIST 8.3 )。 


B LIST 8.3 安装 


$ pip install testfixtures 














testfixtures 的 compare 函数 显示 出 的 错误 信息 比 unittest 的 assertEqual 还 要 详细 。 


from testfixtures import compare 


det test acei): 
result = add(2, 3) 
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compare (result, 5) 








使 用 compare 函数 时 ， 只 需 将 比较 对 象 用 作 实 参 和 直接 执行 即 可 。 
男 外 ， 该 比较 会 递归 地 执行 到 dict 及 list 内 部 ， 并 生成 结果 报告 。 
在 比较 下 面 这 种 复杂 数据 的 时 候 ，compare PAZXBETEZI m zn h list 中 的 diet 元 素 如 何不 同 。 








> combare (lene 1 (Tm > autas orbe mez le 
Mene cb e Ewe s messa ic toomnbeb neaz 


Traceback (most recent call last): 


AssertionError: sequence not as expected: 


same: 


[{'one': 1}] 


ELES 


Pieext rese waloreue nbaz tvo PL 


second: 


Porere e eee boo moze el 


While comparing [1]: dict not as expected: 


same: 


Lewo" | 


values differ: 


text's roowbar udpaz" l= roownbobiubaz' 


While comparing [1] ['text']: 
Qo -1,3 -1,3 QQ 


[oO 





ZA TIT BAD unified diff 格 式 显 示 不 同 。 可 见 ， 它 会 递归 地 根据 数据 类 型 不 同 选用 最 
和 耳 观 的 显示 方法 。 

另外 ， 比 较 方 法 和 结果 输出 可 通过 testfixture.comparison.register 国 数 进行 添加 。 各 位 想 多 
次 重复 使 用 assert 语句 时 不 妨 一 试 。 

使 用 Comparison 类 可 以 一 次 性 查看 对 象 的 属性 。 
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from testfixtures import compare, Comparison as C 


det test Create object) : 
pecu ena (neme="cunmnmy-0o]ect", value=4) 


compare (result, C(SomeObject, name="dummy-object", value-4) 


ShouldRaise 可 以 查看 发 生 的 例外 。 特 别 是 它 连 交 给 例外 的 传 值 参数 都 能 查看 到 ， 这 是 
unittest 的 assertRaises 做 不 到 的 。 











from testfixtures import ShouldRaises 


det test Gricical error tre 
with ShouldRaise (CriticalError('very-critical')): 


Important process (None) 


testfixtures 提供 的 能 应 用 于 单元 测试 的 实用 程序 还 远 不 止 这 些 ， 其 他 还 有 控制 台 输 出 、 日 
志 输 出 等 等 。 加 之 它 可 以 像 普通 的 模块 一 样 对 待 ， 所 以 能 够 在 unittest、nose、pytest 等 
testrunner 上 使 用 。 





e 通过 pytest 执行 测试 

pytest 是 第 三 方 出 品 的 测试 工具 。 它 描述 测试 比 unittest 要 人 简单， 而 且 能 输出 详细 的 错误 报 
告 。pytest 能 够 自动 发 现 并 执行 测试 ， 其 中 包括 用 unittest 写 的 测试 ， 所 以 unittest 与 pytest 完全 
可 以 并 用 。 

pytest 可 以 用 pip 安装 ， 具 体 如 LIST 8.4 所 示 。 





B LIST 8.4 安装 


$ pip install pytest 


pytest 执行 时 会 在 指定 的 目录 (未 指定 状态 下 则 默认 当前 目录 ) 下 寻找 测试 。 这 个 过 程 称 为 
Test Discovery, Python 程序 包 下 的 tests 模块 以 及 “test ** test” 等 形式 的 名 称 都 会 被 识别 为 测 
试 模块 。pytest 发 现 测 试 模块 后 会 执行 该 模块 内 的 测试 并 显示 结 











€ 实际 编写 一 个 测试 并 执行 
建议 不 要 把 测试 放 得 离 测试 对 象 太 远 。 我 们 将 测试 与 测试 对 象 放 在 同一 个 程序 包 内 ， 以 
"test ( 测试 对 象 的 模块 名 } py” 命 名 该 文件 。 接 下 来 用 unittest 写 一 个 测试 用 例 ( LIST 8.5 ). 





© LIST 8.5 测试 对 象 : bankaccount.py 


class NotEnoughFundsException(Exception): 


mA Nor mnough Punce VUn 
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class BankAccount (object): 


diem. ambe o (self): 


selt., balance = 0 


def deposit (self, amount): 


self.balance += amount 


def withdraw (self, amount): 


self.balance -= amount 


leitaegeltml eanec (ee 


recura selz., balance 
cert set balance (selt, ME 
LE value < 0s 
raise NotEnoughFundsException 


self., balance = value 


balance = property (get balance, set balance) 


这 是 一 个 传统 的 BankAccount 教程 。 状 态 只 有 _balance, balance 属性 为 包装 。 其 实际 的 逻 
辑 是 withdraw 和 deposit。 现 在 我 们 把 这 些 测试 写 出 来 。 





E LIST 8.6 测试 类 


import unittest 


class TestBankAccount (unittest.TestCase): 


这 里 创建 一 个 继承 了 unittest. TestCase 的 测试 类 ( LIST 8.6 )。 类 名 没有 特殊 要 求 ， 但 最 好 让 
人 能 明确 分 辨 出 测试 对 象 。 比 如 “Test+ 测试 对 象 类 名 ”这 种 命名 规则 就 很 不 错 。 


© LIST 8.7 ”加 载 测试 对 象 
class TestBankAccount (unittest.TestCase): 
det gerttearget (selt) E 
Lrom bankaccount rmport BankAccount 


return BankAccount 


dercmnuteonedceclt ne tete erc 


perur xml eer rma C) esses n rediere aem) 


HAUS. e 
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这 是 用 来 准备 测试 对 象 的 实用 方法 。 为 防止 模块 的 副作用 对 其 他 测试 产生 影响 ， 这 里 
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单独 导入 (LIST 8.8 )。 
Ə LIST 8.8 测试 方法 


class TestBankAccount(unittest.TestCase): 


Bus 


def 


def 


def 


def 


def 


def 


( 中 间 省 略 ) . . . 


cest construct (self) s 
target = selt, makene () 


self.assertEqual (target. balance, 0) 


cest deposit (selt) s 

carget = selt, makene () 
target.deposit (100) 

Seussasseneaea emer 


test withdraw (self): 
carget = self, makene () 
carget. balance = 100 
target.withdraw (20) 


selt assertHcwel (target. balence, 80) 


cest get balance (selit) s 

rangeri sel cons 

carget. belance = 500 

sell Mas sert Egua lliltarget geti acs QU 


cest set balance (selit) s 

carget = selt., makene (l) 
carget- set balance (500) 

selt assert nene ieu. (target. balance, 500) 


test set balance not enough funds (self): 
carget = self, makene () 
from bankaccount import NotEnoughFundsException 
GEY s 
carget. set balance (-=1) 
self.fail() 
except NotEnoughFundsException: 


pass 


E 
Tf 


me 


测试 方法 要 每 个 方法 分 开 描 述 。 在 _makeOne 方法 内 生成 测试 对 象 的 实例 ， 备 齐 测试 的 前 
提 条 件 ， 然 后 执行 测试 。 测 试 结 采 在 assert* 方法 内 查看 。 会 出 现 例 外 的 测试 要 使 用 fail 方法 ， 
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或 者 用 assertRaises 也 行 。 
执行 pytest 很 简单 ， 只 要 在 描述 测试 的 文件 (test bankaccount.py ) 所 在 的 目录 下 执行 py.test 
即 可 。pytest 会 目 动 找 出 并 执行 测试 ( LIST 8.9 )。 





© LIST 8.9 执行 测试 


$ py.test 


€ 15 FH pytest 插件 

pytest 的 插件 多 种 多 样 ， 比 如 收集 执行 数据 并 进行 解析 的 插件 、 改 变 测试 结果 显示 模式 的 插 
件 ， 等 等 。 除 pytest 目 身 包含 的 插件 外 ， 我 们 还 可 以 选择 使 用 第 三 方 开 发 的 插件 ， 甚 至 目 己 编 
写 插 件 。 





O pytest-cov 

coverage 会 在 执行 命令 时 收集 该 命令 的 信息 。 使 用 pytest-cov 可 以 查看 测试 中 都 执行 了 哪些 
人 代码。 虽然 一 味 育 从 这 个 数值 是 很 危险 的 ,但 Le dd } 未 被 测试 。pytest- 
cov 可 以 通过 pip install pytest-cov 进行 安装 A 76a Hl --cov 选项 指定 要 获取 和 窗 新 率 的 程序 包 。 

















O xunit 


它 和 JUnit 一 样 会 将 测试 pouce 特定 格式 的 文件 中 。 在 与 Jenkins 等 CI 工具 联动 时 会 用 
到 它 。 它 是 pytest 标 配 的 插件 ， 可 以 通过 --junit-xml 选项 添加 使 用 。 


O pdb 
它 会 在 测试 发 生 错 误 时 自动 执行 pdb( Python 的 调试 器 )。 可 以 通过 --pdb 选项 添加 使 用 。 





什么 是 覆盖 率 

覆盖 率 由 百分比 表示 。 比 如 测试 代码 执行 过 了 程序 的 每 一 行 ， xx 
ThE, JUS E BIER LE ZBadxTXXxEÍEBMMSA.-Ti, RER EES 
了 一 遍 而 已 ， 因 此 并 不 能 检测 出 逻辑 错误 引起 的 Bugo AAEN, EunXRTS DAD AUBU AASSUSS 
是 什么 。 履 盖 率 是 用 来 检查 “测试 代码 不 足 、 测 试 存在 芷 漏 ” 的 一 个 指标 , “测试 内 容 是 否 妥 
当 ” 并 不 归 它 管 。 覆 盖 率 按 评测 标准 分 为 3 个 阶段 OREM, ORT )。 

CD 指令 覆盖 率 ( 简称 C0 ) ， 只 要 执行 了 所 有 命令 即 可 。 比 如 存在 if 语句 ， 只 要 测试 代码 从 
f 语句 中 通过 即 可 达到 100%。 

D 分 支 覆盖 率 ( C1): 通过 所 有 分 支 即 可 。 如 果 代 码 中 存在 if..elif..else 这 样 的 分 支 ， 需 要 
Amoa CRUS. 不 村 入 分 二 的 古训 4 ups) 10096. 

O 条 件 覆 盖 率 ( C2): 当 存在 多 个 分 支 条 件 时 ， 测 试 代码 需要 执行 过 所 有 情况 才能 达到 100%。 
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3e 、 分 支 覆 盖 率 、 条 件 履 盖 率 三 者 之 间 ， 后 者 达到 100% 的 难度 都 要 高 于 前 者 。 
7 MIU 到 100% ， 所 以 我 们 通常 希望 能 保证 这 个 100%。 但 是 能 分 给 编写 测试 
代码 的 时 间 毕 竟 有 限 ， 如 果 为 提升 覆盖 率 编 写 大 量 测试 ， 那 么 维护 测试 代码 的 成 本 将 大 大 提升 
( 测试 代码 负债 化 )。 所 以 我 们 应 该 现实 一 点 ， 根 据 眼前 情况 判断 覆盖 率 应 当 达 到 多 高 。 

另外 ， 引 入 覆盖 率 后 ， 大 家 会 发 现 无 意义 的 行 以 及 意 "M oue. ES 
顺便 督促 了 我 们 在 编程 时 应 尽量 避免 出 现 上 述 情况 。 和 SORE EFT 
的 东西 ， 所 以 还 没 接触 过 它 的 朋友 请 务必 一 试 。 


€ 使 用 mock 

mock 是 将 测试 对 象 所 依存 的 对 象 蔡 换 为 虚构 对 象 的 库 。 该 虚构 对 象 的 调用 允许 事后 查看 。 
HIN, EYF E MTS 

mock 可 以 通过 pip 安装 ， 具 体 如 LIST 8.10 所 示 。 











B LIST 8.10 安装 


$ pip install mock 


O 虚构 对 象 
用 mock.Mock 生成 虚构 对 象 。 虚 构 对 象 的 添加 方法 也 很 俐 单 。 虚 构 对 象 生 成 后 ， 用 任何 方 
法 都 可 以 调用 它 。 








soc wmpotomoci 
nomo-omoecl Mole) 


>>> m.something("this-is-dummy-arg") 
用 return. value 可 以 指定 返回 值 。 


>>> momemnmepe ne 
>>> m.something ("this-is-dummy-arg") 


10 


执行 后 可 以 查看 到 mock 的 方法 的 调用 。 


>>> m.something.called 
TUE 
>>> m.something.call args 


(('this-is-dummy-arg',), {}) 


此 外 ， 还 能 指定 让 其 发 生 例外 。 
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>>> M. Cmething. sice ettecrt = Pxeeption ems 
>>> m.something ('this-is-dummy-arg') 


Traceback (most recent call last): 


Exception: oops 


可 以 在 测试 内 使 用 断言 。 





e assert called with 


e assert called once with 








这 些 方法 的 作用 是 在 测试 对 象 的 处 理 执 行 完毕 后 ， 查 看 其 被 调用 的 情况 以 及 被 调用 时 的 传 
值 参 数 。 


>>> M = MOEk. Mock t) 

»»» m.something('spam') 4 一 月 用 
«mock.Mock object at 0x00000000025AF7F0»-» 
>>> M. g0mething assert callec wieni" egg") 


Traceback (most recent call last): 


'Expected: %s\nCalled with: %s' % ((args, kwargs), self.call args) 
AssertionError: Expected: (('egg',), {}) 
Called Wich (an ) 


>>> m.something.assert called with('spam') 

>>> m.something('spam') 4 $8 KHH 

«mock.Mock object at 0x00000000025AF7F0-» 

>>> m.something.assert called once with('spam') 


Traceback (most recent call last): 


raise AssertionError (msg) 


AssertionError: Expected to be called once. Called 2 times. 


O patch 

生成 虚构 对 和 象 后 ， 需 要 将 其 混入 测试 对 象 的 代码 之 中 。 虚 构 对 和 象 用 作 传 值 参 数 的 时 候 最 好 
对 付 ， 只 要 将 其 作为 传 值 参 数 交 出 去 即 可 ,但 处 理 过 程 中 要 用 到 的 类 或 函数 就 不 能 通过 传 值 参 
数 来 传递 了 。 这 种 时 候 ，mock 可 以 在 patch 的 作用 范围 内 将 模块 内 的 类 或 函数 临时 蔡 换 为 虚构 
对 象 ( LIST 8.11 ). 

















EJ LIST 8.11 patch 装饰 器 的 使 用 示例 


Gpatch('myviews.SomeService') 


def test it (MockSomeService): 
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mock opb] = MockSomeService.return value 
mock ©]. something. return value = 10 
from myviews import MyView 

result = MyView() 


assert result = 10 


通过 patch Bf [ELS GB ERR RRN Ro RRK, SCERIAIEL IT] Mock IARE TE ZU 
试 的 传 值 参数 被 传 进去 。 这 个 管 换 仅 在 执行 被 patch 闭 饰 硕 闭 饰 的 函数 的 过 程 中 有 效 ， 所 以 不 会 
对 其 他 测试 造成 影响 。 





@ 如 何 编写 高 效率 的 Python 测试 用 例 

JEE unittest 柑 块 来 写 测 试用 例 并 不 能 让 测试 变 得 高 效 。 写 完 测 试用 例 后 要 多 运行 几 裔 。 为 
外 ， 在 修改 源码 时 如 果 已 经 有 了 内 容 明 确 的 相关 测试 用 例 ， 那 么 要 迅速 且 准 确 地 找 出 受 影 响 的 
部 分 。 另 外 ， 各 个 测试 用 例 要 分 离 得 足够 开 。 如 采 修 改 一 个 测试 用 例 导 致 其 他 测试 用 例 不 能 运 
行 ， 这 将 会 成 为 一 种 负 俩 。 

要 想 最 大 限度 地 巧 用 测试 用 例 ， 需 要 注意 以 下 几 点 。 











。 尺 可 能 人 简单 

要 让 人 从 测试 内 容 中 一 眼看 出 输入 和 输出 。 

尽 可 能 快 ， 多 执行 几 次 

单元 测试 多 执行 几 涡 。 为 实现 这 一 点 ， 要 用 pytest 人 简化 执行 操作 ， 并 且 保 证 测试 本 里 的 执 
行 不 消耗 过 多 时 间 。 如 果 执 行 一 次 就 要 花 去 10 分 钟 ， 那 么 没 人 会 愿意 多 执行 几 遍 的 。 

分 离 各 个 测试 

保证 测试 数据 不 被 多 个 测试 用 例 共享 。 对 一 个 测试 有 用 的 数据 对 其 他 测试 不 一 定 有 用 ， 
如 条 测试 中 包含 了 这 种 没 用 的 数据 ， 会 使 输入 输出 变 得 不 明确 。 另 外 ， 如 采 遇 到 不 得 不 
变更 测试 数据 的 情况 ， 那 么 必须 事先 查 清 其 影响 范围 。 

不 直接 回 模 块 内 import 测试 对 象 

如 果 和 直接 癌 测试 模块 内 import 测 试 对 象 ， 那 么 一 旦 这 个 测试 对 象 的 import 本 里 会 市 来 问 
题 ， 就 会 导致 测试 模块 内 的 所 有 测试 用 例 全 部 无 法 评测 。 此 外 ， 某 些 测试 用 例会 将 
import 失 败 判断 为 错误 。 还 有 ， 如 采 模 块 包含 会 在 import 时 执行 的 代码 ， 那 么 还 没 等 测试 
开始 ， 这 些 代 码 就 完 执行 完毕 了 。 

TR] PATIO Eres 

在 “单元 测试 ”部 分 我 们 已 经 提 过 了 ， 不 要 试图 用 setUp 方 法 做 完 一 切 准 备 工作 。setUp 
不 是 用 来 存放 相同 的 处 理 的 地 方 。 尤 其 不 能 用 setUp 来 生成 依存 于 测试 的 数据 配置 右 。 

不 摘 通 用 的 数据 配置 大 

通用 的 数据 配置 希 (Data Fixture) 会 在 测试 之 间 建 立 依存 性 。 在 单元 测试 阶段 ， 要 保证 
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只 在 测试 用 例 中 创建 必要 的 输入 数据 。 

不 过 分 信任 虚构 对 象 

mock 库 可 以 轻松 分 离 测试 对 象 。 但 是 不 能 过 分 依赖 于 mock。 正 因为 mock 人 简单 ， 我 们 才 
容易 被 它 允 。 另 外 ， 检 查 一 下 是 不 是 写 了 “在 mock 返 回 了 mock 之 后 返回 一 个 mock” 这 
种 mock。 这 么 复杂 的 mock 真 的 是 模仿 其 他 组 件 做 出 来 的 ? 这 种 mock 会 让 输入 输出 变 得 
檬 糊 ， 同 时 导致 关联 度 上 升 。 在 制作 mock 上 费 脑 筋 是 一 个 危险 信号 ， 此 时 应 该 重新 审视 


设计 方案 。 











8.2.3 JASPER SANE PRG 


要 保证 单元 测试 不 依赖 于 环境 ， 只 执行 测试 对 象 本 里 。 否 则 ， 每 当 其 所 依赖 的 模块 或 外 部 
系统 的 运作 稍 有 变化 就 要 对 测试 进行 一 次 修改 ,这样 单元 测试 皮 眼 间 就 会 成 为 一 种 负 作 。 





€ 请 求 / 响应 
View 的 形式 有 许多 种 。 接 下 来 我 们 选 Python 框 染 中 几 种 常见 的 模式 各 写 一 个 测试 。 


O View 类 

View 类 是 用 类 定义 的 View (LIST 8.12 )。 它 不 是 单纯 的 函数 ， 所 以 可 以 使 用 属性 和 方法 ， 
使 得 结构 更 加 多 变 。View 的 处 理 在 类 的 方法 中 进行 定义 ,测试 时 用 dummy HAXE, R 
们 就 能 做 到 只 运行 测试 对 象 的 方法 了 。 

使 用 View 类 时 ， 大 部 分 框 淋 会 用 构造 函数 来 接收 请 求 ， 通 过 方法 来 进行 View 的 处 理 。 此 
时 能 很 轻松 地 用 dummy BERK AIh, BIA View 会 调用 服务 以 及 读 取 模型 ， 不 过 我 们 完全 
可 以 用 mock REREN] Œ View 的 输出 中 ，HTTP 啊 应 是 方法 的 返回 值 ， 它 能 被 视 为 啊 应 对 
象 。 对 于 这 种 状态 ，View 绝 大 多 数 时 候 虱 已 经 做 完了 HTML ER., ET HTML 内 容 的 多 变性 ， 
测试 时 最 好 确认 一 下 交 给 模板 的 传 值 参 数 。 




















© LIST 8.12” 暴 型 的 View 类 


class MyView (object): 
cet _—_ dmit _ (self, request): 


self.request = request 


def index(self): 


s = SomeService() 
result = s.some method (**self.request .params) 
return render('index.html', dict (result=result)) 





MAPAREN P AAN. 
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(D 把 SomeService 替换 为 mock 
D 获取 传 给 render 的 dict 的 内 容 


© LIST 8.13 更 便于 测试 的 View 类 


class MyView(object): 


someservice cls = SomeService 
duc — ç imit (self, Tecwest) E 
self.request = request 


diem sehe» (exire 
EE Ecciceusscc cd 
result = s.some method (**self.request.params) 
selt, render Context = CLOT (result=result) 


return render (' index Mremi", Selt, render Context) 


把 SomeService 替换 为 mock 的 最 简单 方法 就 是 把 它 放 在 类 里 。 田 外 ， 只 要 把 dict 的 内 容 放 
在 对 象 里 ， 我 们 就 能 在 测试 中 查看 它 了 (LIST 8.14 )。 








四 LIST8.14 test 


class DummyRequest (object) : 
det c imit (self, parems) s 


self.params = params 


class DummySomeService (object): 
def somemethod (self, **kwargs): 


return kwargs 


class TestIt(unittest.TestCase): 
det test it(selrT) e 
request = DummyRequest (params={'a': 1]) 


target = MyView (request) 


target .someservice cls = DummySomeService 
result = target.index() 
self.assertEqual(target.render context['result'], {'a': 1}) 
EB 
€ 全 局 请 求 对 象 


某 些 框架 会 把 请 求 对 象 当 作 一 个 线程 本 地 化 的 全 局 对 象 提 供给 我 们 。 更 改 它 们 需要 对 框架 
进行 调整 ， 所 以 必须 加 以 注意 。 为 外 ， 有 些 时 候 框 架 根 本 不 允许 我 们 对 请 求 对 象 进行 修改 。 对 
于 这 类 情况 ,框架 一 般 都 会 提供 一 个 从 框架 传送 虚拟 请 求 的 机 制 ， 我 们 要 利用 这 一 机 制 来 控制 
输入 (LIST 8.15), Flask 就 属于 这 类 框架 。 
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© LIST 8.15 test 


with app.test_request_context: 


result = myview() 


IMR f, Flask 的 view 的 返回 值 是 啊 应 体 。 而 且 view 是 个 函数 ， 没 地 方 存储 传 给 模 
板 的 上 下 文 。 其 实 有 一 个 地 方 可 以 用 ， 那 就 是 请 求 对 象 ( LIST 8.16 ). 


© LIST 8.16 myviews.py 


def index (): 
s = SomeService() 
result = s.some method (**self.request.params) 
Tecquest S robs noL [E "render Context] el (result=result) 


retum render ("index armil! ccr render Context) 


把 上 下 文 添 加 到 request.environ 中 ， 事 后 可 以 通过 测试 用 例 查 看 。 此 外 ， 在 框架 内 部 使 用 
的 ApplicationModel 等 也 会 变 得 难以 蔡 换 。 到 这 里 ， 我 们 上 自然 希望 mock 等 专用 库 伸 出 援手 。 不 
过 别 急 ， 我 们 先 不 用 库 ， 直 接 混 和 人 些 dummy 试 试 。 











det test che (LE 
import myviews 
SomeService orig = myview.SomeService 
CEV S 
myviews.SomeService = DummySomeService 
app = flask.Flask( name ) 


with app.test_request_context: 


result = myview () 
assert flask.request.environ['render context'] == {'a': 1] 
Elm le 
myviews.SomeService = SomeService orig 





TA, XXTEOMUMTATU I KRRIT, RTE E ANI Pix dixePBESUSIETE 511. XX 
种 时 候 ， 使 用 mock 库 就 简单 得 多 。 





Gpatch('myviews.SomeService!) 

det test Dae (MoOCkSomeservice) s 
myviews.SomeService = DummySomeService 
app = flask.Flask( name ) 
with app.test request context: 


result = myview() 


assert flask.request.environ['render context'] == {'a': 1] 
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由 于 问题 的 根本 在 于 测试 对 象 会 直接 返回 啊 应 体 ， 所 以 我 们 用 闭 饰 融 来 避 开 它 。 


def render view (name) 
det cec (view tune) : 
def wraps () 
deta = view Tune D) 
mel seestelent Neem s nene aaa) 
return wraps 


return dec 





Bæ, WRA EMASNA, RIR REEMA Y eH) F EITA, Hre 
m FME, RERE T RARAS F ELTRAAIPUBUOT A KZ 





def render view (name) 
cert cee (view tune) < 
def wraps () 
data = view tune () 
return render template (name, data) 
Waal ee = yiew Tume 
return wraps 


return dec 


这 样 一 来 ,我们 就 能 在 测试 中 和 直接 查看 返回 值 了 。 





@patch('myviews.SomeService') 

Glen essen alie QQutexellidexet e exer aste rete) e 
myviews.SomeService - DummySomeService 
app = flask.Flask( name ) 
with app.test request context: 


result = myview.inner() 


assert result -- [('a': 1} 


@ 数据 库 

SQLAlchemy 支持 sqlite 的 内 存 数 据 库 。 使 用 内 存 数 据 库 时 ， 可 以 在 不 具备 实际 数据 库 的 情 
况 下 测试 伴随 数据 库 连 接 的 处 理 。 男 外 ，SQLAlchemy H DBSession 对 和 象 进 行 访问 数据 库 以 及 
取出 、 更 新 DomainModel 的 操作 。 

我 们 继续 按照 本 和 草 中 的 设计 ， 将 View 能 直接 访问 的 Model 限制 在 一 个 。 涉 及 多 个 
DomainModel 的 处 理 交 给 ApplicationModel 来 应 付 。 这 样 一 来 ，View 就 只 会 从 DBSession WE 
一 个 模型 了 。 它 对 DBSession 的 调用 是 输出 ， 从 DBSession 获取 的 内 容 是 输入 。 

输入 大 致 分 为 两 种 情况 ， 即 存在 DomainModel 的 情况 和 不 存在 DomainModel 的 情况 。 在 测 
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试 对 象 执行 前 将 DomainModel 放 到 ( 或 不 放 到 ) Sh (session) 内 ， 这 样 ， 我 们 就 能 轻松 控制 这 
两 种 情况 了 。DomainModel 的 调用 方法 要 限制 在 一 个 。 需 要 调用 多 个 时 交 给 ApplicationModel 
来 处 理 。 

由 于 存在 实际 访问 数据 库 的 行为 ， 所 以 测试 前 后 需要 用 配置 融 来 设置 数据 库 。 另 外 ， 我 们 
不 必 每 次 测试 都 设置 一 裔 数据 库 ， 因 此 要 选用 模块 配置 右 。 

首先 编写 一 个 实用 程序 用 作 设 置 数 据 库 的 配置 器 ( LIST 8.17 )。 




















© LIST 8.17 数据 库 配 置疑 


def setup db(): 
from .models import DBSession, Base 
from sqlalchemy import create engine 
engine = create engine("sglite:///") 
DBSession.remove() 
DBSession.configure (bind-engine) 
Base.metadata.create_all(bind=engine) 


return DBSession 


def teardown db(): 


from .models import DBSession, Base 


DBSession.rollback () 
Basenmersadaranreoona Ne BSes on ne 


DBSession.remove() 
在 实际 的 测试 套件 中 ， 通 过 模块 配置 器 调用 上 述 实用 程序 (LIST 8.18 )。 


© LIST 8.18 测试 
def setUpModule () : 
_Setup Ge 


def tearDownModule(): 
 teardown db() 


class TestMyView(unittest.TestCase): 
def setUp(self): 
from .models import DBSession 


self.session = DBSession 


det _sertup entry (self, ecu eiu 
from .models import Entry 


entry = Entry (**kwargs) 
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self.session.add(entry) 


CC UE TEE ETE A 


det test E cc E 


e = elf, setup entry name es Ss exse) 
resulte = self., callrur mec ce 


self.assertEqual(result['name'], e.name) 


测试 数据 的 生成 不 要 在 setUp 中 进行 。 保 证 在 测试 方法 内 只 生成 该 测试 所 需 的 数据 。 

一 旦 用 setUp 生成 测试 数据 ， 这 些 测试 数据 就 会 被 多 个 测试 共 圣 。 被 共 圣 的 测试 数据 会 给 
各 个 测试 之 间 带 来 依存 性 。 

多 余数 据 会 使 输入 输出 变 得 不 明确 。 而 输入 输出 一 旦 不 明确 ， 会 让 人 很 难 搞 清 到 底 在 测试 
什么 。 邦 外， 当前 提 改 变 后 ， 如 果 我 们 对 测试 数据 进行 更 改 ， 其 影响 的 测试 可 能 导致 有 问题 的 
数据 残留 在 程序 中 。 所 以 ， 我 们 需要 证 单元 测试 只 能 给 各 个 测试 准备 该 测试 所 需 的 数据 ， 并 要 
在 保证 没有 多 余数 据 的 情况 下 进行 测试 。 























€ 系统 时 间 

我 们 以 判断 系统 时 间 是 否 为 月 未 的 实用 程序 为 例 来 思考 一 人 下。 系统 时 间 每 次 调用 都 会 返回 
不 同 的 值 ， 所 以 做 自动 测试 时 要 花 些 心思 才 行 。 这 里 我 们 和 暂且 把 系统 时 间 放 在 一 边 ， 先 编写 一 
个 通过 传 什 参数 接收 时 间 并 进行 判断 的 实用 程序 ， 然 后 再 写 一 个 函数 来 给 这 个 传 值 参数 传递 系 
统 时 间 C LIST 8.19, LIST 8.20 )。 

















© LIST 8.19 ”实现 通过 传 值 参数 接收 时 间 并 进行 判断 的 实用 程序 
cet ig last of momen (cl) s 


return (d + timedelta(l)).day == 
接 下 来 进行 测试 。 


det test le last Ot monta eo: 
@ = dete ogg 1l, 30) 


assert 16 last or monthalc), "ss" % el 


det test is last Ot month nor |) e 
@ = darte (2011, 1l, 29) 


assert not is last of month(d), "%s" % d 
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© LIST 8.20 ”实现 用 系统 时 间 进 行 判断 的 实用 程序 
det 1g last Or monta mow () s 


return is last oft month (cdarcetime. now) ) 
把 这 个 也 测试 一 遍 。 获 取 时 间 部 分 使 用 testfixtures 的 Replacer 和 test date. 
from datetime import datetime,date 


cet test lg last Or momcima wi 
with Replacer() as r: 
Caere ("util datetime", test Certe (COGOR TL 11, 30) ) 


assert is last or monta now h) 





XE ER datetime.datetime, MERR RAMA A import 的 东西 (本 例 中 测试 对 象 使 
用 的 是 util.datetime )。 在 ApplicationModel 或 DomainModel 中 使 用 的 时 候 ， 要 用 mock Pre 
is last of month now。 


S: HFEF RE — xe 8 Hir 80. ERIT ERE 


8.2.4 用 WebTest 做 功能 测试 


确认 所 有 组 件 运 转正 和 常 后 ， 就 该 把 它们 结合 起 来 ， 查 看 功能 的 运作 情况 了 。 

对 于 Web 应 用 而 言 ， 功 能 测试 要 查看 从 接受 请 求 到 作出 响应 的 整个 过 程 是 否 正 常 运作 。 系 
统 内 部 的 所 有 组 件 都 直接 使 用 正式 代码 ， 与 外 部 系统 联动 的 部 分 用 mock, mock 部 分 要 尽 可 能 
小 。 男 外 ， 如 果 这 一 阶段 能 拿 到 与 相当 于 正式 运营 时 的 示例 数据 ， 那 就 更 应 该 积极 测试 了 。 

本 阶段 通过 内 存 数 据 库 、 模 拟 请 求 等 来 控制 输入 输出 部 分 。 内 存 数据 库 用 SQLite 的 内 存 
数据 库 即 可 。 由 于 OR BRE LH. db dx E RDBMS 的 差异 ， 所 以 用 作 功 能 测试 缂 年 
ARo 

至 于 模拟 请 求 ， 用 WebTest 比较 容易 实现 。 


























€ WebrTest 

WebTest 是 用 于 Web 应 用 功能 测试 的 库 。 它 会 对 WSGI 应 用 执行 模拟 请 求 并 获取 结果 。 基 
本 上 所 有 WSGI 应 用 的 测试 都 可 以 用 它 。 

WebTest 可 以 用 pip ITX% ( LIST 8.21 )。 





B LIST 8.21 安装 


$ pip install webtest 
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加 LIST 8.22 使 用 方法 


Gem test cue) 
from webtest import TestApp 
import myproject.app 
app = TestApp (myproject.app) 
res = app.get('/'") 


assert "Hello" in res 
lli LIST 8.22 所 示 ，WebTest 中 的 webtest.TestApp HJ LU ERE RRA He [ELA GEO WSGI 
应 用 类 型 的 测试 对 象 ( 比如 myproject.app ). TestApp 拥有 get. post 等 方法 。 它 可 以 利用 这 些 方 
法 来 执行 WSGI 应 用 ， 接 收 啊 应 对 象 。 在 测试 过 程 中 ， 要 测试 啊 应 对 象 的 内 容 以 及 执行 测试 之 
后 的 数据 库 的 状态 等 。 





NOTE 


WSGI( Web Server Gateway Interface, Web 服务 器 网 关 接 口 ) 是 PEP 3333 ”所 倡导 的 
机 制 。 

WSGI 将 Web 服务 器 与 Web 应 用 之 间 的 处 理 定义 成 了 简洁 统一 的 接口 ， 符 合 WSGI 标准 
的 服务 器 以 及 应 用 之 间 可 以 相互 替换 ， 对 应 WSGI 的 应 用 可 以 在 任意 对 应 WSGI 的 服务 器 上 
E. 

比如 在 gunicorn 上 运行 的 Web 应 用 可 以 直接 放 到 Apache 的 mod.wsgi 上 运行 。 

关于 在 gunicorn 上 运行 WSGI 应 用 的 方法 ， 我 们 将 在 第 12 章 中 了 解 。 


e 配置 器 
让 WSGI 应 用 能 通过 WebTest 调用 模拟 请 求 。 另 外 ， 还 要 在 数据 库 配 置 锅 和 数据 库 中 生成 
必要 的 数据 以 及 为 外 部 服务 准备 mock。 











e 测试 用 例 
一 个 请 求 对 应 一 个 测试 用 例 。 设 置 好 配置 带 之 后 ， 通 过 WebTest 发 送 模拟 请 求 。 


@ 断言 

当 渐 言 的 对 和 象 为 HTML 时， 响应 输出 的 内 容 很 容易 变化 ， 所 以 要 检查 由 HTML 输出 的 内 容 
是 否 以 字符 串 形式 包含 在 其 中 。 功 能 的 输出 多 为 更 新 DB， 所 以 直接 检 查 DB 的 数据 即 可 。 另 
外 ， 外 部 系统 的 调用 也 属于 输出 ， 这 部 分 要 通过 mock 的 功能 来 查看 。 











— 


(D nttps://www.python.org/dev/peps/pep-3333 
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€ 与 外 部 服务 有 关 的 测试 
这 里 假设 要 使 用 外 部 的 搜索 服务 。 此 时 只 将 调用 服务 的 部 分 答 换 为 mock。 态 外， 负责 生 成 
数据 的 配置 豆 要 生成 测试 内 所 需 的 内 容 。 


Tome ciem eS i: ei 


from webtest import TestApp 


def setUpModule (): 
_eetup Cls() 


def tearDownModule(): 
_teardown_db() 


cet imit darca) : 
# 在 这 里 生成 数据 


det imit Search rTestlts C) s 


# 在 这 里 创建 mock 的 外 部 服务 结果 
class TestWithMock(unittest.TestCase): 


dier. ge rspeee (selt) s: 
from app import myapp 
app = TestApp (myapp) 


return app 


Gpatch('othersite.search'!) 
cet test ir (mock search) s: 
"uN 测试 "nn 


# 前 提 条 件 
mock search.return value = init search results () 


imit Caral) 


# 准备 测试 对 象 
apo = selt, getTtarget () 


# 执行 测试 对 象 


res = app.get('/?search word=abcd') 


# 确认 结 
accorto es 


mock account depost. assert called EN e 
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这 里 我 们 假设 测试 对 象 myapp 在 内 部 通过 othersite.search 困 数 调用 了 外 部 服务 。 测 试 时 
othersite.search 被 替换 为 mock, 


e 与 认证 和 会 话 相 关 的 测试 

大 部 分 WSGI 应 用 会 将 认证 信息 放 在 environ[REMOTE USER'] 里 ( 非 此 类 框架 的 原理 也 是 
相同 的 ， 只 需 将 存储 位 置 蔡 换 为 该 框架 的 存储 位 置 即 可 ), WebTest 文 持 Cookie， 所 以 能 正常 执 
行 基于 Cookie 的 会 话 及 认证 的 相关 测试 。 


E LIST 8.23 Cookie 的 相关 测试 


from webob.dec import wsgify 


Qwsgify 

def myapp (request): 
cocosmtorequest.cookres.get('counk', "0")) 
Tegqguest response. Set Cookie ("count (ee 


return "response $d" % c 


Gem. test LE() s 
from webtest import TestApp 
app = TestApp (myapp) 
res = app.get('/') 


assert res.body == "response 0" 


res app gece( /7) 


assert res.body == "response 1" 


如 果 不 是 与 认证 本 号 直接 关联 ， 那 么 on extra environ 的 REMOTE USER 里 直接 进行 
设置 。 下 面 是 直接 将 REMOTE USER 传递 给 extra environ 的 例子 。 


© LIST 8.24 ”认证 相关 的 测试 
@wsgify 
def myapp (request): 
if not request.remote user: 


return HTTPFound(location="/login") 
OCU Mom" 
der mmnaleone e 


from webtest import TestApp 
return TestApp (myapp) 
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def callAUT(url, params-[], method-"GET", remote user=None): 
extra environ = ('REMOTE USER': remote user] 
LE mMethoc C TU 
return _ makene () -get 
url, params=params, extra_environ=extra_environ) 
elit method == up OST 
return makeOne() .post\( 


url, params=params, extra environ=extra environ) 
det test witha ces () s 
result =  callAUT('/', remote user-'dummy') 


assert result.body == "OK! 


cer cest vae aro de dioe um) 





result =  callAuT('/') 
assert result. location == mod 
R 0 DUAE 。 REMANER IIIA remote user 最 


后 将 通过 WebTest 的 extra environ 被 传递 给 in dé ( WSGI uiis ) 的 environ, 


8.3 ”通过 测试 改 民 设计 








前 面 我 们 谈 了 一 系列 仅 执行 测试 对 象 的 测试 。 不 知 各 位 在 写 测试 时 是 否 觉 得 举步维艰 ， 是 
否 把 mock 写 得 非常 复杂 ?为 什么 测试 会 变 得 复杂 呢 ?” 要 知道 ， 组 件 之 间 的 结合 度 越 高 ， 给 测 
试 做 准备 就 越 花 时 间 ， 测 试 也 就 越 复杂 。 光 是 蔡 换 mock 都 已 经 要 绞 尽 脑汁 ， 怎 么 可 能 轻松 添 
加 新 功能 呢 ? 因此 我 们 要 根据 测试 结果 来 改良 设计 。 


便于 测试 的 设计 


什么 样 的 设计 便于 测试 呢 ? 首先 结合 度 要 低 。 模 块 间 的 关联 越 少 ， 测 试 起 来 就 越 向 单 。 发 
外 就 是 内 聚 度 要 高 。 梗 块 做 的 事 越 少 测试 越 简单 。 
@ 面向 对 象 原则 

面 回 对 象 程序 设计 有 几 个 原则 。 这 等 这 些 原则 能 让 我 们 的 设计 更 加 便于 测试 。 当 然 ， 有 时 
也 要 勇于 打破 它们 。 不 过 ， 如 末 没 有 特殊 原因 ， 应 尽量 还 循 面 问 对 象 原 则 进行 设计 。 





O 单一 职责 原则 
保证 一 个 对 象 只 具有 一 项 职责 ， 一 项 职责 只 由 一 个 对 象 来 负责 。 如 于 只 顾 眼 前 方便 而 育 目 





220 | 第 2 部 分 团队 开发 的 周期 








仍 求 对 象 的 通用 性 ， 就 很 容 多 生成 大 得 吓人 的 类 。 所 以 我 们 应 根据 单一 职责 原则 ， 将 正确 的 方 
法 放 到 正确 的 类 中 。 名 如 HogeManager 的 类 往往 都 是 未 经 过 整理 的 类 。 给 类 起 这 种 名 字 目 然 无 
妨 ， 但 具体 的 处 理 最 好 别 写 在 HogeManager 中 。 有 具体 的 处 理应 该 在 Model 中 实现 ， 然 后 让 
HogeManager 只 负责 调用 即 可 。 这 样 做 有 助 于 提高 内 聚 度 。 











O 接口 隔离 原则 

即 不 依赖 于 没有 必要 的 接口 。Python 的 语法 中 没有 接口 的 概念 ， 但 仍然 会 直到 类 似 问 题 。 
比如 一 旦 我 们 进行 了 类 检查 ,那么 传 值 参 数 将 只 能 接受 该 类 或 其 子 类 。 然 而 Python 文 持 鸭子 类 
型 ( Duck Typing )， 非 子 类 也 可 以 答 换 使 用 ， 所 以 最 好 不 要 做 类 型 检验 ， 而 是 根据 类 内 是 否 存在 
东方 法 来 判定 传 值 参数 ， 从 而 使 模型 结构 更 加 灵活 。 




















O 开放 封闭 原则 

对 扩展 开放 ， 对 修改 封闭 。 一 个 模块 的 修改 不 带 来 额外 的 派生 ， 同 时 模块 具有 可 扩展 性 。 
将 某 个 类 的 对 象 奉 换 为 其 子 类 的 对 象 时 ， 不 需 在 扩展 的 基础 上 再 修改 其 他 模块 。 

这 类 替换 必须 遵循 特定 条 件 ， 并 不 是 说 用 类 和 继承 随时 都 能 实现 。 














O E REREN] 

子 类 替换 父 类 的 过 程 对 调用 方 透明 。 这 要 求 我 们 在 定义 子 类 时 ， 宽 松 对 竺 其 能 接受 的 内 容 ， 
严格 把 关 其 返回 的 内 容 。 

在 下 述 情 况 下 ， 父 类 不 可 以 替换 为 子 类 。 





e 了 于 类 会 发 生父 类 不 允许 发 生 的 例外 

。 了 于 类 不 接受 父 类 已 有 的 参数 

e 了 于 类 返回 父 类 不 返回 的 值 

。 父 类 中 实现 的 内 容 在 子 类 中 被 重 载 ， 但 并 未 实现 相关 处 理 








如 条 只 是 想 加 强 代码 的 通用 性 ， 那 么 应 该 尽量 重视 复 用 ， 少 用 继承 。 


O 复 用 优先 于 继承 

继承 是 一 种 紧密 的 结合 ， 因 为 我 们 无 法 将 子 类 与 父 类 彻底 分 离 。 复 用 则 不 同 ， 它 也 是 对 已 
有 代码 的 一 种 再 利用 ， 但 不 会 产生 继承 关系 。 另 外 ， 复 用 人 允许 我 们 在 测试 时 用 虚拟 对 象 替换 原 
对 象 。 从 对 象 角度 看 ， 父 类 与 子 类 属于 同一 个 东西 ， 从 模块 角度 看 则 不 然 。 
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NOTE 
面向 对 象 程序 设计 的 原则 并 不 止 这 5 个 。 本 章 仅 是 从 活用 测试 结果 的 角度 挑选 了 几 个 加 以 
说 明 。 


8.4 ”推进 测试 自动 化 


测试 要 做 到 让 任何 人 都 能 随时 执行 。 因 为 这 种 任何 人 都 能 随时 执行 的 测试 可 以 自动 化 。 后 
面 的 章节 中 我 们 将 介绍 CI 工具 (Continuous Integration Tool， 持 续集 成 工具 )， 它 能 够 在 我 们 问 
版 本 库 提 交代 码 时 目 动 执行 测试 ， 并 返回 一 个 规整 的 测试 结果 报告 。 

执行 测试 和 提交 测试 代码 通常 部 是 开发 者 的 工作 。 此 时 各 位 不 妨 回想 一 下 昨天 的 情况 。 测 
试用 例 增加 了 吗 ? 测试 用例 中 通过 测试 的 比例 变 了 吗 ? 徐 盖 率 怎么 样 ? 

目 动 化 的 CI 工具 会 为 我 们 持续 保存 这 些 测试 结果 。 它 能 帮助 我 们 更 有 效 地 利用 测试 结 
并 且 可 以 使 用 已 提交 至 版 本 库 的 正式 代码 进行 测试 (毕竟 谁 都 难免 有 忘记 提交 的 时 候 )， 从 而 及 
早 发 现 源码 乃至 开发 效率 上 的 种 种 问题 。 

CI 工具 的 用 法 我 们 放 到 后 面 的 章节 再 和 学习。 本草 匀 余 的 部 分 ， 我 们 用 来 给 CI 工具 铺路 ， 
学 习 一 下 如 何 搭建 让 任何 人 都 能 随时 执行 测试 的 环境 。 





























8.4.1 用 tox 自动 生成 执行 测试 的 环境 


tox 能 便捷 地 为 我 们 准备 好 执行 测试 所 需 的 环境 。tox 会 在 多 个 virtualenv 环境 中 搭建 测试 
环境 ， 然 后 在 这 些 环境 中 执行 测试 并 显示 结果 。 它 能 够 把 测试 工具 的 选项 及 环境 变量 等 内 容 统 
一 起 来 ， 所 以 我 们 只 需 执行 cox 命令 即 能 轻松 完成 所 需 的 测试 。 

如 下 所 示 ， 可 以 用 pip 安装 tox. 





cH Same ad bo 


安装 完成 后 ，tox 命令 丈 能 用 了 。 执 行 tox 时 需要 用 到 tox.ini 文件 ， 我 们 要 在 这 个 文件 中 
描述 测试 环境 的 设置 。 各 个 环境 的 设置 由 所 用 Python 的 版 本 、 环 境 变 量 、 测 试 所 需 的 库 、 执 行 
测试 的 代码 等 组 成 。 

下 面 是 tox.ini 文件 的 一 个 例子 。 








[TOK] 
envlist = py26,py27,flake8 


Skipsdist - true 
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[testenv] 

deps - pytest 
webtest 
testfixtures 
mock 


-rrequirements.txt 
commands = py.test 


[testenv:flake8] 
basepython = python2.7 
deps = flake8 


commands = flake8 


[tox] 方 的 envlist 用 于 设置 测试 环境 列表 。 这 里 我 们 用 到 了 py27. py26 和 flake8 这 3 个 环 
境 。py27 是 个 特殊 的 名 字 ， 它 会 找 出 当前 已 安装 的 python2 .7 命令 并 生成 virtualenv. 

另外 ， 我 们 在 skipsdist 选项 中 进行 了 设置 ， 保 证 即使 没有 setup.py 也 能 执行 测试 。 在 没有 
setup.py 的 情况 下 ， 依 赖 库 由 requirements.txt 等 进行 管理 。 关 于 依赖 库 的 管理 ， 我 们 将 在 9.2 n 
再次 进行 学 习 。 

[testenv] 方 用 来 进行 测试 环境 的 设置 。 如 有 果 存 在 [testenv:flake8] 这 种 指定 了 环境 名 的 节 ， 则 
优先 采用 该 方 的 设置 。 环 境 未 被 特别 指定 时 ， 使 用 [testenv] 区 的 通用 设置 。 

在 这 个 tox.ini 文件 所 在 的 目录 下 执行 tox 之 后 ， 以 下 测试 将 会 被 执行 。 











e 在 python2.6 生成 的 virtualenv 内 执行 py . test 
e 在 python2 .7 生成 的 virtualenv 内 执行 py . test 
e 在 python2 .7 生成 的 virtualenv 内 执行 flake8 


为 外 ,使 用 -e 选项 可 以 对 指定 环境 进行 测试 。 


$ tox -e py27 
$ tox -e flake8 
可 见 ，tox 能 将 多 种 不 同 的 测试 执行 方法 统一 成 一 个 。 为 外 ， 由 于 每 个 测试 都 被 分 离 在 各 
目的 virtualenv 内 ， 所 以 更 改 一 个 测试 的 设置 不 会 对 其 他 测试 造成 影响 。 用 Python 2.6 和 2.7 两 
个 版 本 进行 测试 就 是 很 好 的 例子 。 不 仅 如 此 ， 即 便 是 Web 应 用 框架 等 大 程序 库 的 不 同 版 本 测 
iX, tox 同样 能 发 挥 作用 。 
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8.4.2 ”可 重复 使 用 的 测试 环境 


要 想 让 测试 能 够 重复 进行 ， 必 须 能 够 随时 准备 出 完全 相同 的 环境 。 如 果 上 一 次 测试 生成 的 
文件 或 数据 残留 在 环境 中 ， 很 可 能 会 对 新 一 次 测试 造成 影响 。 所 以 测试 结束 后 ， 千 万 记得 要 用 
tearDown 方法 清理 测试 环境 。 态 外 ， 考 虑 到 前 一 次 测试 可 能 由 于 出 错 等 原因 以 中 断 的 形式 残留 
在 里 面 ， 最 好 在 测试 开始 时 和 绪 束 时 都 调用 一 志清 理 方法 。 清 理 的 对 象 包括 测试 用 数据 库 、 目 
有 录 、 外 部 系统 的 过 程 等 。 











8.5 小结 





本 章 讲 解 了 便于 测试 的 设计 方法 以 及 高 效 的 测试 手法 。 高 效 的 测试 具备 以 下 特点 。 
。 测试 对 象 明 确 

。 测试 要 检查 的 内 容 明 确 

。 可 任意 次 重复 执行 





进行 这 类 测试 必须 吻 除 环境 依赖 。 本 革 也 一 直 是 这 样 做 的 ， 让 测试 对 和 象 不 依赖 于 环境 ， 仪 
执行 测试 对 象 。 

测试 同样 能 验证 应 用 的 正确 性 ， 有 助 于 品质 的 提升 。 不 仅 如 此 ,便于 测试 的 设计 拥有 低 结 
合 高 内 聚 的 特点 ， 通 过 将 各 目 独 立 的 组 件 组 合 在 一 起 来 实现 功能 。 充 分 独立 的 组 件 所 组 成 的 绪 
构 有 春 很 好 的 可 维护 性 和 可 扩展 性 。 

莱 顾 到 测试 的 设计 可 以 为 我 们 市 来 如 此 多 的 好 处 ， 何 乐 而 不 为 呢 ? 


第 9 章 Python 封装 及 其 运用 


本 章 将 对 程序 包 的 使 用 方法 和 运用 技巧 进行 介绍 。 

在 第 3 章 中 ， 我 们 已 经 介绍 了 Python 项 目的 结构 。 本 章 内 容 可 视 为 其 后 续 ， 为 各 位 讲解 包 
的 使 用 方法 ， 包 括 可 用 于 试 运行 环境 和 正式 环 蒂 的 部 署 、 为 执行 测试 的 部 署 等 方面 。 只 要 包 的 
使 用 方法 和 封 疼 方 法 得 当 ， 测 试 及 部 署 的 目 动 化 也 会 侧 单 很 多 。 另 外 ， 根 据 实 际 情况 ， 我 们 往 
往 需 要 满足 一 些 弟 规 处 理 之 外 的 条 件 。 加 深 对 封 深 的 理解 ， 有 助 于 各 位 应 对 这 些 特殊 情况 ， 人 免 
除 为 其 单独 花费 工夫 的 抹 烦 。 

本 革 还 将 进一步 深入 地 讲解 pip 的 用 法 。 此 外 ， 我 们 还 将 学 习 一 些 其 在 用 法 上 的 组 合 技巧 ， 
带 助 我 们 活用 pip。 








9.1 使 用 程序 包 
本 部 分 将 介绍 一 些 能 应 用 于 部 署 及 自动 测试 的 pip 功能 。 


9.1.1 程序 包 的 版 本 指定 


有 些 时 候 ， 我 们 需要 安装 一 些 特 定 版 本 的 程序 包 ， 比 如 想 查看 某 版 本 下 的 运行 情况 ， 或 者 
需要 用 到 某 个 版 本 之 前 的 最 后 一 版 。 

指定 程序 包 版 本 的 方法 有 几 个 。 以 pip install colander 为 例 ，colander 是 用 于 模式 定义 和 校 
验 的 Python 程序 包 。 我 们 用 几 种 不 同方 式 来 安 半 指定 版 本 (LIST 9.1 )。 





























© LIST 9.1 指定 版 本 的 方法 
pip install -U colander .0 : 最 新 的 稳定 版 

.0 : 指定 版 本 

.9.9 : 1.0 版 以 前 的 最 后 一 个 稳定 版 


ili 
Di rmsrall -U olander==1.0" il 
0 
1.0bl : 1.0 版 以 前 的 最 后 一 个 版 本 
1 
0 


pio imstall -U Tcolancderei, 0" 


aod T& XE RUN 
.0 : 1.0 版 以 前 的 最 后 一 个 稳定 版 ( 包括 1.0 版) 
.9.8 : 0.9 BR (R8 ) bm 0.9.9 大 以 前 的 最 后 至 个 栓 定 版 


pupoumnscvatl Uuccotander-sd 057 


# 
# 
^ 
install -U "colander«1.0" --pre H 
E 
BlD ingtall u"colLlarndess-dq3 0 H 

# 


Xr Xr UU ror Xr 
Toj 
n 
O 


Dip rmsrtall -U "ceolanders»=0.9,<0.9,9" 


可 见 ， 指定 版 本 的 方法 并 不 唯一 。 某 些 指定 方法 需要 用 双 引 号 “"” 插 起 来 。 这 是 防止 不 等 
E “<” “>” H shell 解释 为 重 定 问 。 
为 了 便于 理解 ， 我 们 这 里 指定 了 -U (C--upgrade) 选项 ， 因 此 即便 指定 程序 包 已 存在 于 计算 
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HF, ASUDABPHÉECR dH. 

HAIR, pip 不 会 安装 alpha flit, beta 版 等 预 发 布 版 本 的 程序 包 。 至 于 某 有 版 本 是 否 为 预 发 布 版 
本 ， 可 以 看 版 本 号 是 否 像 1.3al 、1.3bl 这 样 后 面 跟着 al bl (在 PEP 440” 中 有 相关 定义 )。 要 
安装 上 述 预 发 布 版 本 时 ， 需 要 明确 指定 版 本 号 ， 或 者 附加 --pre 选项 。 











C3 版 本 命名 规范 与 大 小 关系 

版 本 的 命名 规范 ( 结构 ) 与 大 小 关系 在 PEP 440 中 有 相关 规定 。 

版 本 号 要 遵循 [NIJN(.N)*[falblc}N][.postN][.devN] 的 结构 。N 可 以 为 正 整数 或 0。(.N)* 可 以 
重复 出 现任 意 次 。 被 [] 括 起 来 的 部 分 可 以 省 略 。a、b、<c 分 别 代 表 alpha, beta. rco 

各 版 本 号 的 先后 顺序 自然 不 能 根据 字符 串 排序 来 定 ， 其 编号 方 陈 及 排序 大 致 如 LIST 9.2 
所 示 。 


B LIST 9.2 版 本 的 编号 方式 及 排序 


.9.1 
.10 
.0al.devi 


0 

0 

l 

L 

I 
1.0b2 
1 

1 
1.0-post1 
l 


«uil 





实际 上 ， 版 本 号 这 东西 我 们 很 少 会 在 命令 行 指定 。 大 多 是 在 setup.py 中 指定 版 本 时 才 会 用 
到 它 。 

举 个 例子 ， 假 设 我 们 为 Python 2.7 开发 的 myapp 程序 依赖 于 名 叫 securelib 的 外 部 库 。 然 而 
securelib 从 1.0 版 之 后 才 开 始 提供 我 们 所 需 的 功能 ， 所 以 必须 指定 安装 1.0 以 后 的 版 本 ( LIST 
9.3 )。 现 阶段 的 情况 是 ，myapp 的 setup.py 中 并 没有 给 install requires 指定 版 本 号 。 这 种 情况 
下 ， 如 末 计 算 机 中 已 经 装 有 securelib， 那 么 其 版 本 将 不 会 被 更 新 。 一 旦 使 用 者 环境 中 安 闭 的 是 
不 提供 所 需 功 能 的 旧版 本 ， 程 序 将 无 法 正常 运行 。 











加 LIST 9.3 在 setup.py 中 指定 依赖 库 为 1.0 以 后 的 版 本 


setup ( 


name-'myapp', 


(D nttps://www.python.org/dev/peps/pep-0440 
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ingtall recgquires=| 
!eecurelbap--i-9t 


l, 


这 里 如 果 指 定 securelib--1.0 又 会 市 来 别 的 问题 。 因 为 这 样 一 来 ， 只 要 我 们 使 用 myapp， 
securelib 的 版 本 就 会 被 限制 在 1.0。 就 算 securelib 因为 安全 问题 发 布 了 1.0.1, myapp 的 使 用 者 
也 只 能 继续 用 securelib-1.0。 为 避免 这 类 问题 ， 要 尽量 避免 在 setup.py 中 指定 固定 版 本 。 

接 下 来 了 解 一 下 为 一 种 情况 ， 就 是 指定 某 版 本 之 前 的 版 本 。 比 如 securelib-3.0 发 布 ， 其 使 用 
的 API 发 生 了 重大 变更 。 此 时 如 有 果 安 装 myapp 时 安装 了 3.0, JE myapp 将 无 法 正常 工作 。 为 防 
止 这 个 情况 发 生 ， 可 以 给 myapp 追加 一 条 指定 ， 指 定 其 使 用 securelib-3.0 之 前 的 版 本 ( LIST 9.4 )。 














加 LIST 9.4 在 setup.py 中 指定 依赖 库 为 1.0 以 后 、3.0 以 前 的 版 本 


setup ( 


name='myapp'", 


ingtall recquires= | 
'gecurelibs=1, ocu 


] 





做 过 上 述 修改 后 ， 就 能 让 使 用 者 安装 正确 版 本 的 程序 包 ， 保 证 myapp 正常 运行 了 。 


NOTE 

本 例 中 ，myapp 选择 使 用 旧版 本 的 securelib。 然 而 ， 如 果 程 序 一 直 依 赖 于 旧版 本 的 
securelib， 将 无 法 使 用 今后 推出 的 安全 更 新 。 所 以 根据 API 的 变更 重新 修改 、 测 试 myapp， 让 
其 支持 securelib-3.0 才 是 比较 好 的 选择 6 


9.1.2 JAdE PyPI 服务 器 安装 程序 包 


pip 搜索 程序 包 时 默认 引用 PyPI 的 URL”。 需 要 引用 PyPI 以 外 的 服务 器 时 ， 有 两 个 选项 可 
供 使 用 。 

-i ( --index-url ) 选项 可 以 指定 其 他 兼容 服务 需 来 代 蔡 PyPI。 这 些 服务 需 被 称 为 index 服务 
器 ，PEP 301”、PEP 438” 中 对 它们 的 规格 有 着 严格 规定 。 举 个 例子 ， 当 我 们 想 从 PyPI 的 测试 服 








(D https://pypi.python.org/simple 
2 nhttps://www.python.org/dev/peps/pep-0301 
© https://www.python.org/dev/peps/pep-0438 
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Hd (D x y m 3 动 = 
务 和 项” 安 痛 程序 包 时 ， 可 以 像 下 面 这 样 执行 。 
$ pip install bpbook -i https://testpypi.python.org/simple 


同样 地 ， 我 们 可 以 在 公司 内 搭建 蔡 代 PyPI 的 index 服务 器 ， 用 pip 从 该 服务 器 上 进行 安装 。 
PyPI 上 公开 了 多 种 搭建 PyPI 替代 服务 器 的 方法 ,其 中 devpi” 可 以 给 每 个 用 户 设置 多 个 索引 , 同 
时 具备 PyPI 镜像 功能 ， 非 常 好 用 。 

另 一 个 用 起 来 更 方便 的 选项 是 find-links。-f ( --find-links ) 选项 用 来 指定 包含 目标 程序 包 链 
接 的 页 面 。 该 选项 指定 的 页 面 所 链接 的 程序 包 会 优先 于 index 服务 器 。 如 果 在 指定 页 面 没 有 找 
到 目标 程序 包 ， 计 算 机 则 会 引用 index 服务 器 内 的 资源 进行 安装 。 




















$ pip install -f https://bitbucket.org/shimizukawa/logfilter/downloads logfilter 
Downloading/unpacking logfilter 

Downloading logfilter-0.9.2.zip 

Running setup.py egg_info for package logfilter 


像 上 面 例子 中 这 样 ， 指 定 -f 选 项 后 ， 计 算 机 便 会 检查 该 页 面 内 的 链接 ， 识别 程 序 包 名 称 ， 
自动 获取 并 安装 最 新 版 本 。 不 过 ，pip install 只 能 识别 符合 规定 的 正确 包 名 。 规 定 大 致 如 下 。 











{ 包 名 }-{ 版 本 号 } ( - {平台})?.{ 扩展 名 )} 


指定 平 合 的 部 分 可 以 省 略 。 如 末 一 个 程序 包 指 定 了 平台 (如 win32 )， 那 证 明 它 在 其 他 平台 
上 是 无 法 运行 的 。 因 此 ，pip 只 会 寻找 并 安 疙 适合 当前 平台 的 程序 包 。 








安装 未 存放 于 PyPl 的 程序 包 
有 些 程序 包 虽 然 被 添加 到 了 PyPl， 但 实际 的 程序 包 文 件 却 存 放 在 其 他 地 方 。 这 种 程序 包 无 
法 用 pip install 程序 包 名 的 方式 进行 安装 ， 所 以 必须 指定 --allow-external 选项 。 
$ pip install --allow-external 程序 包 名 
另外 ， 如 果 程 序 包 被 存放 在 http 环境 而 非 https 环境 下 ，pip 会 认为 程序 包 有 可 能 在 通讯 中 
被 自 改 ， 因 此 会 中 断 安装 。 在 迫不得已 一 定 要 使 用 这 类 程序 包 的 情况 下 ， 请 指定 --allow- 


unverified 选项 。 


$ pip install --allow-unverified 程序 包 名 


(D https://testpypi.python.org/ 
2 https://pypi.python.org/pypi/devpi 
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已 删除 的 PyPI 镜像 规格 

PEP 381” 对 PyPI 镜像 服务 器 规格 作 了 规定 。 但 随 着 CDN 等 技术 的 应 用 , 以 及 PyPI 服务 器 
逐渐 稳定 , 镜像 服务 器 规格 的 删除 在 PEP 464” 中 被 提出 ， 并 最 终于 2014 年 春 完成 删除 。 因 此 ， 
如 今 已 不 需要 用 --index-url 选项 引用 宰 像 服务 器 。 男 外 ， 曾 经 的 --use-mirror 选项 也 于 pip-1.5 
起 被 删除 。 

曾 提 供 服 务 的 a.pypi.python.org、b.…… 之 类 的 镜像 服务 器 的 域名 早已 废止 。 现 在 使 用 旧版 
本 pip， 通 过 环境 变量 或 设置 将 镜像 引用 设 为 有 效 后 ，pip 有 可 能 不 正常 工作 。 因 此 请 各 位 避免 
使 用 那些 会 引用 镜像 服务 器 的 选项 。 


9.1.3 程序 包 的 发 布 格式 


如 今 上 传 到 PyPI 的 程序 包 大 多 采用 sdist 格式 。sdist 是 包含 程序 包 元 数据 及 构建 方法 的 存 
档 格 式 。 它 会 在 每 次 安装 时 谈 取 各 环境 的 设置 ， 存 在 C 扩 展 时 进行 构建 ， 然 后 检查 所 需 的 
Python 程序 包 并 复制 到 site-packages。 男 外 ，sdist 中 其 实 有 许多 文件 并 不 会 被 安装 。 这 些 工 作 
在 每 个 平台 上 实施 一 次 就 足够 了 。 相 对 地 ， 二 进 制 包 的 特点 是 仅 包含 已 构建 完毕 的 C 扩展 和 
Python 程序 包 ， 仅 解压 程序 包 的 存档 即 可 完成 安 靶 。 

Python 的 二 进 制 包 长 期 以 来 使 用 着 setuptools 实现 的 egg 格式。 但 是 pip 并 不 支持 egg 格式 
的 程序 包 ， 这 导致 该 格式 在 普及 的 道路 上 一 直 停滞 不 前 。 随 着 Python 封装 的 规范 化 ，PEP 427^ 
提出 了 一 个 能 克服 egg 缺点 的 wheel 格式 。 加 之 pip 也 开始 支持 wheel 格式 ， 所 以 其 很 快 在 部 署 
等 方面 得 到 应 用 。 

已 上 传 到 PyPI 的 wheel 格式 程序 包 可 以 通过 pip 直接 安装 。 接 下 来 ， 我 们 以 安装 Django 为 
例 来 学 习 一 下 。 

















$ pip install django 
Downloading/unpacking django 

Downloading Django-1.7.1-py2.py3-none-any.whl (7.4MB): 7.4MB downloaded 

Storing download in cache at /var/pip-chache/https$3A$2F$2Fpypi.python. 
org$2Fpackages$2Fpy2.py3$2FD$2FDjango$2FDjango-1.7.1-py2.py3-none-any.whl d 
Installing collected packages: django 
Successfully installed django 


Cleaning up... 


(D nttps://www.python.org/dev/peps/pep-0381 
2 https://www.python.org/dev/peps/pep-0464 
© https://www.python.org/dev/peps/pep-0427 
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可 以 看 到 计算 机 从 PyPI 下载 了 wheel 格式 的 程序 包 。pip 是 从 1.5 版 以 后 开始 正式 支持 
wheel 格式 的 。 这 里 我 们 将 pip 的 版 本 降 回 1.4， 然 后 再 安装 Django 试 试 。 


$ prp-install django 
Downloading/unpacking django 
Downlosdsudgebsyeandgo-d1 7 tar GZ (07 5SME) sven al 
Storing download in cache at /home/aodag/.pip/eggs/https$3A$2F$2Fpypi.python. 
org£2Fpackages$2Fsource£e2FD£$2FDjango$2FDjango-1.7.1.tar.gz d 
Running setup.py egg_info for package django 


warning: no previously-included files matching '__pycache__' found under 
directory "*! J 

warning: no previously-included files matching '*.pylcol' found under dire 
GORY X d 


Installing collected packages: django 
Running setup.py install for django 


varming: No previously- inelucded files matching t __pycache _" rone under 

directory "'"*! d 
warning: no previously-included files matching '*.py[co]' found under 

directory aai d 
changing mode of build/scripts-2.7/django-admin.py from 644 to 755 
changing mode of /home/aodag/works/bpbook2015/djangoenv/bin/django-admin. 

po 55 d 
Installing django-admin script to /home/aodag/works/bpbook2015/djangoenv/bin 

Successfully installed django 


Cleaning up... 


可 以 看 到 ， 这 种 情 a tar.gz 存档 的 sdist 进行 的 。 另 外 ， 相 较 于 通过 wheel 
HITR, iil sdist 进行 安 痰 时 ， 下 载 后 的 处 理 要 多 出 很 多 。 

对 于 Django 这 种 不 包含 C 扩 展 的 程序 包 而 言 ， 上 面 的 差距 还 算 可 以 接受 。 可 是 一 旦 换 成 
Pillow 这 种 包含 CPR, H C 扩展 需要 大 量 依 赖 库 的 程序 包 时 ， 差 中 就 无 法 忽视 了 。 现 在 PyPI 
上 提供 了 支持 各 种 Python 版 本 及 CPU 的 wheel 格式 Windows 版 Pillow 程序 包 ， 即 便 是 在 难以 
准备 编译 磊 的 Windows 环境 下 ， 也 只 需要 通过 pip ETT Re B n] JF 568: H] Pillow 了 。 


EZ-:9 wheel 程序 包 的 文件 名 
PEP 427 ”中 规定 了 wheel 程序 包 的 命名 规则 。 自 此 ，wheel 程序 包 依赖 于 哪个 版 本 的 
Python 以 及 哪个 OS， 仅 和 赁 包 名 即 可 一 目 了 然 。 


(D nttps://www.python.org/dev/peps/pep-0427 
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其 命名 与 解释 规则 如 下 。 
(distribution]-[version) (-[build tag])?-(python tag}-{abi tag]-(platform tag}.whl 


LIST 9.5 是 一 些 已 上 传 到 PyPI 的 程序 包 的 文件 名 。 


加 LIST9.5 wheel 程序 包 文 件 名 示例 


bpmappers-0.7-py2-none-any.whl 

Django-1.7.1-py2.py3-none-any.whl 

MarkupSafe-0.23-cp27-none-linux x86 64.whl 
Pillow-2.6.1-cp32-cp32m-macosx 10 6 intel.macosx 10 9 intel.macosx 10 9 x86 64. 


whl 


9.1.4 ÆW wheelhouse 的 方法 


wheel 格式 的 程序 包 方 便 好 用 ， 但 我 们 前 面 也 说 了 ，PyPI 上 大 部 分 程序 包 都 是 sdist 格式 。 
为 方便 今后 在 CI 工具 上 和 部 署 时 能 有 wheel 可 用 ， 我 们 来 学 习 一 下 如 何 根据 sdist 生成 wheel。 
pip 可 以 通过 wheel 命令 将 PyPI 上 只 提供 了 sdist 的 程序 包 转 换 成 wheel 格式 并 保存 在 本 地 计算 
机 中 。 本 地 的 wheel 格式 程序 包 默 认 保存 在 wheelhouse 目录 下 ， 也 正 因 为 如 此 ， 我 们 习惯 将 所 
有 保存 wheel 格式 程序 包 的 目录 都 称 为 wheelhouse ( 与 实际 目录 名 称 无 关 )。 使 用 wheel 命令 前 ， 
需要 先 安装 wheel 包 。 


$ pip install wheel 
接 下 来 ,我们 以 生成 Pillow 的 wheel 为 例 实际 生成 一 个 wheelhouse, 


$ pip wheel pillow 
Downloading/unpacking pillow 
Downloddung Prllow-2-6 lotargz (7-3MB)S V/-3MB downloaded 


Running setup.py egg_info for package pillow 


Building wheels for collected packages: pillow 

Running Setup Oy bdiste wheel tor pillow 

Destination directory: /home/aodag/works/bpbook2015/wheelhouse 
Successfully built pillow 


Cleaning up... 


$ ls wheelhouse/ -1 
-rw-r--r-- 1 bp bp 714085 11H 10 19:31 Pillow-2.6.1-cp27-none-linux x86 64.whl 
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可 见 ，pip 和 wheel 组 合 使 用 之 后 ， 可 以 将 只 提供 了 sdist 的 程序 包 转 换 为 wheel 格式 保存 。 


NOTE 

生成 并 保存 在 wheelhouse 里 的 wheel 依赖 于 执行 wheel 命令 的 平台 。 库 中 包含 C 扩展 的 
wheel 不 具备 跨 平 台 通 用 性 。 比 如 正式 服务 器 使 用 Linux 但 开发 者 使 用 OS X， 就 需要 准备 一 个 
与 正式 服务 器 同 平台 的 CI 服务器， 在 上 面 执 行 生 成 wheelhouse 的 任务 。 


9.1.5 从 wheelhouse 安装 


现在 我 们 来 学 习 如 何 安 装 wheelhouse 内 的 程序 包 。 最 简单 的 方法 就 是 用 pip install 直接 指 
定 wheelhouse 目录 下 的 文件 。 


$ pip install wheelhouse/Pillow-2.6.1-cp27-none-linux x86 64.whl 
Unpacking ./wheelhouse/Pillow-2.6.1-cp27-none-linux x86 64.whl 
Installing collected packages: Pillow 

Successfully installed Pillow 


Cleosmugng opes 


由 于 C 扩展 的 编译 等 处 理 在 这 个 阶段 早已 完成 ， 所 以 安装 会 十 分 迅速 。 不 过 ，wheel 格式 
程序 包 的 文件 名 通 稼 比较 复杂 ， 每 次 安装 都 手动 输入 实在 麻烦 。 
EX, HÆJ -f( --find-links ) 指定 wheelhouse 目录 ， 程序 包 名 部 分 就 可 以 只 写 Pillow T- 





$ pip install -f wheelhouse pillow 
Downloading/unpacking pillow 
Installing collected packages: pillow 
Successfully installed pillow 


Cleaning up... 





保险 起 见 ， 我 们 添上 --no-index 选项 以 防 wheelhouse 以 外 的 目录 被 引用 。 


$ pip install --no-index -f wheelhouse pillow 
Ignoring indexes: https://pypi.python.org/simple/ 
Downloading/unpacking pillow 

Installing collected packages: pillow 
Successfully installed pillow 


Cleaning up... 


事先 在 wheelhouse 目录 下 生成 的 wheel 格式 程序 包 都 可 以 通过 上 述 步 又 进行 安装 。 只 要 将 
所 有 依赖 库 全 都 放 到 wheelhouse 下 ， 我 们 就 可 以 脱 机 完成 环境 搭建 。 男 外 ， 由 于 安装 时 所 需 的 
处 理 极 少 ， 所 以 非常 适合 需要 多 次 重复 搭建 相同 环境 的 情况 。 为 部 署 和 CI 工具 搭建 环境 时 ， 请 
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务必 记得 运用 wheelhouse 目录 。 


9.2 巧 用 程序 包 








在 需要 多 次 重复 安 疼 的 时 候 ，wheel 格式 的 程序 包 显 得 十 分 便捷 。 接 下 来 我 们 学 习 一 下 如 何 
将 其 巧 用 到 CI 和 部 署 中 去 。 


9.2.1 私密 发 布 


有 了 时候 我 们 需要 用 到 未 在 PyPI 上 公开 的 程序 包 ， 比 如 不 能 在 PyPI 上 公开 的 公司 内 部 库 ， 
或 者 一 些 经 过 修改 但 尚未 正式 发 布 的 库 等 。 

这 种 时 候 ， 可 以 借助 版 本 库 服 务 需 提供 的 功能 做 私密 发 布 。 私 密 发 布 一 般 用 来 做 程序 包公 
开 到 PyPI 前 的 测试 ， 以 及 给 一 些 不 想 添加 到 PyPI 但 仍 需 安排 版 本 号 的 程序 包 做 内 部 公开 。 前 
面 我 们 学 习 了 和 直接 从 版 本 库 进行 安装 的 方法 ,使 用 者 可 以 通过 这 个 方法 获取 目标 版 本 的 程序 包 ， 
其 过 程 与 程序 包 作 者 本 人 的 意图 基本 无 关 。 

Github 和 Bitbucket 会 以 标签 名 或 分 文 名 为 单位 提供 zip 或 其 他 格式 的 源码 文件 。 同 时 ， 通 
过 使 用 pip 指定 包含 程序 包 名 称 的 完整 URL， 可 以 绕 过 索引 服务 器 直接 安装 程序 包 。 将 这 两 个 
组 合 在 一 起 ， 我 们 就 能 安装 已 私密 发 布 但 尚未 在 PyPI 发 布 的 程序 包 了 。 

举 个 例子 ， 有 个 名 为 logfilter 的 工具 ， 其 源码 在 Bitbucket 中 公开 管理 。 这 个 工具 并 未 在 
PyPI 上 公开 程序 包 ， 因 此 不 能 通过 pip install logfilter 进行 安装 。 但 是 ， 如 果 我 们 像 LIST 9.6 这 
样 直接 指定 URL， 就 能 够 完成 安装 了 。 


























B LIST 9.6 ”安装 已 私密 发 布 的 程序 包 


$ pip install https://bitbucket.org/shimizukawa/logfilter/get/logfilter-0.9.2.zip 


9.2.2 I5FH requirements.txt 





HH pip freeze 命令 可 以 查看 通过 pip 安装 的 依赖 库 的 内 容 。 如 果 将 这 些 内 容 保 存在 文件 
中 ,再 用 pip install 的 -r 选项 指定 这 个 文件 ， 在 该 环境 中 安装 的 库 就 可 以 在 其 他 环境 中 被 


$ pip freeze > requirements.txt 


$ pip install -r requirements.txt 


多 数 项 目 都 将 依赖 库 的 列表 保存 在 了 requirements.txt 文件 中 。 不 过 ，requirements.txt 能 做 
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的 事 还 远 不 止 于 此 。 

requirements.txt 内 部 可 以 引用 其 他 requirements.txt。 比 方 说 我 们 要 把 只 在 开发 时 才 需 要 的 库 
和 执行 时 需要 的 库 分 开 管 理 。 此 时 ， 我 们 需要 把 测试 运行 融和 配置 硕 工 具 写 在 tests-require.txt 
文件 里 ， 把 执行 时 需要 的 库 写 在 requirements.txt 文件 里 。 这 种 情况 下 ， 只 要 准备 一 个 如 
LIST 9.7 所 示 的 dev-requires.txt， 束 能 通过 一 条 pip install -r dev-requires.txt 完成 开 
发 者 环境 的 准备 工作 。 





© LIST 9.7 dev-requires.txt 


-r requirements.txt 


-r tests-require.txt 


另外 ， 建 议 将 --allow-external 和 --allow-unverified 等 常用 选项 也 一 并 写 在 dev-requires.txt 
中 。 这 样 可 以 将 选项 与 requirements.txt 分 离 ， 人 免得 在 使 用 pip freeze > requirements .txt 


自动 生成 文件 时 丢失 选项 。 


9.2.3 requirements.txt 层级 化 


接 下 来 ， 我 们 考虑 对 requirements.txt 进行 分 割 。 前 先 ，requirements.txt 是 许多 工具 默认 识 
别 的 文件 名 ， 所 以 这 个 文件 名 的 重要 性 最 高 ， 要 用 来 保存 执行 时 所 需 程 序 库 的 列表 。 接 下 来 考 
不 开发 者 使 用 的 工具 。 这 部 分 可 以 按 用 途 分 为 测试 工具 、 文 档 生 成 、 模 式 迁 移 等 多 个 类 别 。 我 
们 为 每 个 用 途 分 别 准备 一 个 文件 。 

LIST 9.8 ~ LIST 9.12 表示 的 就 是 一 个 文件 分 割 的 例子 。 























© LIST 9.8 requirements.txt 


pyramidis 
sqlalchemy==0.9.8 
psycopg22z2s2.5.4 


© LIST 9.9 tests-require.txt 


pytest2-2.6.4 
pylestecovssl 8. 1 
GOVenaele Er 


webtest==2.0.6 


© LIST 9.10 docs-require.txt 


Sq 2 
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© LIST 9.11 db-requires.txt 


atembaec--Q 6-7 
psycopg2222.5.4 


© LIST 9.12 dev-requires.txt 


--no-index 

-f http://devpi/-«myproject/simple 
-r requirements.txt 

-r tests-require.txt 

-r docs-require.txt 


-r db-requires.txt 


这 样 设置 下 来 之 后 ， 就 不 会 在 执行 时 安装 一 些 没 用 的 库 了 。 同 时 ，tests-require.txt 等 还 可 以 
拿 到 其 他 项 目 之 中 重复 利用 。 


9.2.4 为 部 署 和 Cl+tox 准备 的 requiremests 


前 面 我 们 学 习 过 ， 用 pip 能 够 将 依赖 库 以 wheel 格式 保存 在 wheelhouse 里 。 为 方便 将 它们 
运用 到 CI 和 部 署 当中 ， 我 们 要 简化 这 些 依赖 库 的 安 疙 流程 。 

用 pip 管理 程序 包 的 情况 下 ， 依 赖 库 会 记录 在 requirements.txt 中 。 这 里 我 们 跟前 面 一 样 ， 
在 requirements.txt 里 只 保存 依赖 库 的 列表 。 

然后 ， 为 了 在 搭建 环境 时 只 从 wheelhouse 获取 这 些 库 ， 我 们 像 LIST 9.13 这 样 编写 dev- 
requires.txt， 将 库 的 获取 位 置 限定 为 wheelhouse。 














© LIST 9.13 dev-requires.txt 
-f wheelhoouse 
--no-index 


-r requirements.txt 





有 了 这 些 文件 之 后 ， 就 可 以 用 下 述 方法 从 wheelhouse 进行 安装 了 。 
$ pip install -r dev-requires.txt 


接 下 来 ， 我 们 把 它 应 用 到 我 们 在 8.4.1 市 和 学习 过 的 测试 环境 工具 tox Es tox 可 以 在 
virtualenv 中 为 每 个 测试 环境 搭建 一 个 虚拟 环境 ， 如 果 能 通过 wheel 格式 给 各 个 环境 安装 依赖 库 ， 
那么 必 将 提升 搭建 环境 的 效率 。 

tox 可 以 在 tox.ini 文件 中 指定 安装 到 环境 的 库 (LIST 9.14 )。 由 于 这 部 分 是 直接 交 给 pip 处 
理 的 ， 所 以 指定 的 东西 不 一 定 非 要 是 库 ， 还 可 以 是 requirements.txt 等 文件 。 
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© LIST 9.14 tox.ini 


[testenv] 


deps = -rdev-requires.txt 





这 样 设置 下 来 之 后 ， 计 算 机 就 会 根据 dev-requires.txt 从 本 地 的 wheelhouse 安装 依赖 库 。 这 
里 有 一 点 需要 注意 ，tox 不 会 查看 dev-requires.txt, requirements.txt 这 类 文件 的 内 容 ， 所 以 如 果 
我 们 对 这 些 文件 进行 了 编辑 ， 需 要 手动 执行 带 --recreate 选项 的 tox 命令 。 


$ tox --recreate 





虽然 难以 避免 上 述 这 类 麻烦 ， 但 对 于 某 些 需要 频繁 重 置 环境 的 CI 工具 而 言 ， 它 仍 是 一 个 非 
常 省 时 省 力 的 方法 。 特 别 是 使 用 travis.ci 等 对 执行 时 间 有 限制 的 工具 时 ， 缩 短 搭 建 环境 的 时 间 
显得 十 分 重要 。 





9.2.5 通过 requirements.txt 指定 库 的 版 本 


我 们 在 用 pip freeze 生成 的 requirements.txt 文件 中 指定 了 库 的 版 本 。 通 过 requirements. 
txt 指定 版 本 的 方法 有 很 多 种 ， 这 里 我 们 学 习 直 接 指 定 版 本 的 方法 。 ai n ri. MERE 
修复 Bug， 也 可 能 导致 其 运行 出 现 变 化 。 因 此 ， 开 发 、 测 试 、 正 式 环境 要 保证 使 用 同 版 本 的 库 。 
CI 工具 可 以 用 tox 的 --recreate 选项 来 严格 按照 requirements.txt 中 mem 库 重 新 搭建 环境 。 另 
外 ， 想 知道 环境 中 是 否 安 装 了 未 包含 在 requirements.txt 中 的 库 时 ， 可 以 通过 pip freeze 指定 
requirements.txt 进行 查看 ( LIST 9.15 )。 

















回 LIST 9.15 ”查看 是 否 安 装 了 未 包含 在 requirements.txt 中 的 库 
$ pip freeze -r requirements.txt 
随 着 程序 库 版 本 不 断 更 新 ，wheelhouse 内 的 文件 会 越 积 越 多 。 我 们 可 以 通过 下 述 方法 将 未 
包含 在 requirements.txt 中 的 库 转 移 到 其 他 目录 。 


S$ mv wheelhouse wheelhouse.old 


$ pip wheel -r requirements.txt -f wheelhouse.old 


XE AE EIE ES. HIMA I gi d IRE h AUE TEL ER Ar RIR reg HJ JUS o 3oC EST IC n e 
些 心 思 来 规避 风险 了 ， 比 如 在 virtualenv 上 重新 搭建 一 个 环境 ， 然 后 切换 nginx 等 反问 代理 的 








花 
化 
XB 


* 
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93 h% 


本 章 介 绍 了 程序 包 的 使 用 方法 和 使 用 技巧 。 正 如 本 音 所 说 的 ， 巧 用 pip 可 以 为 测试 和 部 署 
的 自动 化 减轻 很 多 负担 。 硕 望 各 位 能 以 本 章 介绍 的 方法 为 参考 ， 人 研究 出 适合 各 自 项 目的 结构 。 
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不 知 各 位 有 没有 遇 到 过 这 种 事 一 一 在 自己 的 环境 里 运行 一 切 正常 的 程序 放 到 开发 环境 和 正 
式 环境 中 却 突然 无 法 运行 了 。 如 果 有 ， 那 么 在 导致 无 法 运行 的 原因 中 ， 有 没有 遗漏 提交 或 者 忘 
记 安 装 关 键 程序 呢 ? 

这 些 恼 人 的 低级 错误 往往 会 导致 我 们 被 经 理 叫 去 面谈 ， 出 错 经 过 被 刨 根 问 底 ， 最 后 被 迫 
“ 写 个 应 对 方案 出 来 "， 心 情 沉重 好 几 天 。 麻 烦 的 是 ， 就 算 我 们 在 发 现 问 题 的 涉 几 天 能 提前 注意 ， 
暂时 避免 问题 的 重复 发 生 ， 但 是 随 着 时 间 推 移 早 晚 还 会 再 犯 ， 结果 还 是 得 对 着 经 理 铁 青 的 脸 咽 
茜 水 。 相 信 不 少 人 都 有 过 类 似 经 历 吧 ? 

如 果 每 次 修改 程序 都 重新 构建 、 测 试 、 检 查 测 试 结果 ， 我 们 或 许 能 避免 上 述 失 误 。 但 是 ， 
人 类 是 一 种 不 擅长 单调 重复 劳作 的 生物 。 所 以 ， 我 们 需要 借助 工具 让 这 一 系列 工作 的 执行 自动 
化 、 定 期 化 。 

这 种 自动化、 定期 化 执行 的 解决 方案 称 为 持续 集成 ( Continuous Integration，CI )。 这 个 解决 方案 
极 大 降低 了 各 种 人 为 失误 (粗心 大 意 、 重 复 劳 作 的 惰性 等 ) 带 来 的 风险 。 本 章 将 以 Django 框架 的 
Web 应 用 为 例 ， 讲 解 如 何 用 CI 工具 Jenkins 实现 持续 集成 。Django 的 相关 知识 请 参考 第 14 3t, 






































10.1 什么 是 持续 集成 


10.1.1 持续 集成 的 简介 


€ 开发 流程 中 存在 的 风险 

持续 集成 是 一 种 让 计算 机 自动 地 任意 次 重复 整个 开发 流程 ( 编译、 测试 、 汇 报 等 ) 的 开发 
手法 ， 一 般 简 称 为 CI。 由 于 其 频繁 重复 整个 开发 流程 ， 所 以 能 帮助 开发 者 提早 发 现 问题 。 

为 方便 理解 持续 集成 ， 现 在 我 们 把 从 写 代 码 到 向 执行 环境 发 布 的 整个 开发 流程 大 致 分 为 以 
平 E. 


OD 编写 源码 。 修 改 已 有 代码 
© FESZ. push 
(3) 进行 发 布 


在 @ 和 @) 的 过 程 中 容易 出 现下 述 问 题 ， 必 须 严 加 注意 。 
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e 遗漏 提交 。 忘 记 提 交 要 发 布 的 程序 
e 遗漏 合并 。push 到 default 的 时 候 忘 记 合并 ， 出 现 多 头 现象 
。 遗漏 安装 。 编 写 的 程序 需要 特定 Python 模块 才能 运行 ， 但 是 忘记 安装 该 模块 了 





对 于 这 类 问题 ， 只 要 事先 准备 好 测试 代码 ， 在 程序 发 布 到 目标 环境 之 前 执行 测试 ， 基 本 都 
BEDA BAL. 


€ 长 期 开发 中 容易 出 现 的 问题 

我 们 都 希望 测试 代码 在 发 布 之 后 仍 能 够 长 期 继续 使 用 。 毕 葛 开 发 是 一 个 持续 的 过 程 ， 一 次 
发 布 之 后 还 会 有 下 一 次 发 布 ， 并 不 是 发 布 一 次 就 结束 了 o 

在 开发 长 期 持续 的 过 程 中 ， 我 们 会 遇 到 下 面 这 些 问 题 。 











O 忘记 以 前 发 布 的 代码 
肩负 程序 修改 任务 的 开发 者 对 源码 的 修改 十 分 敏感 ， 会 频繁 地 执行 测试 代码 。 可 是 , 一旦 
修改 任务 结束 ， 问 题 关 闭 ， 就 很 少 有 人 再 愿意 回 过 头 去 手动 执行 那些 已 经 通过 的 测试 了 。 


O 只 关心 自己 负责 的 部 分 

大 部 分 时 候 ， 我 们 会 去 执行 与 日 己 负责 部 分 相关 的 测试 代码 ， 但 不 会 关心 责任 范围 以 外 的 
模型 的 测试 。 然 而 ， 我 们 对 程序 的 修改 有 时 会 “ 枪 躬 ” 邱 茶 些 看 似 蛇 无 天 系 的 模 英 的 测试 结 
舍 计 各 位 之 中 有 不 少 人 有 过 类 似 经 历 。 

可 见 ， 我 们 很 难 通过 人 为 的 注意 和 操作 来 确认 整个 开发 流程 ， 而 且 这 样 做 也 是 一 种 时 间 和 
务 动 力 的 少 费 。 如 末 项 目 代码 量 很 大 ， 那 么 执行 所 有 测试 代码 必然 消耗 大 量 时 间 ， 如 采 人 是 在 目 
己 的 环境 中 执行 ， 这 根本 不 现实 。 所 以 这 类 工作 最 好 交 给 计算 机 去 做 。 








€ 一 天 内 多 构建 几 次 能 很 快 发 现 问题 
一 天 内 多 次 定期 pull 源码 并 运行 测试 代码 可 以 帮助 我 们 及 早 发 现 问题 。 与 其 等 到 后 期 一 次 性 
找 出 一 大 推 问题 ， 不 如 在 产生 问题 时 及 早 处 理 来 得 方便 和 放心 。 这 一 做 法 被 我 们 称 为 持续 集成 。 


NOTE 


持续 集成 是 XP (Extreme Programming, WIRT ) 的 最 佳 实践 之 一 。 原 文 出 自 Martin 
Fowler 的 论文 ， 各 位 可 通过 下 述 URL 查看 。 


O 国际 著名 的 面向 对 象 分 析 设 计 、UML、 模 式 等 方面 的 专家 ， 敏 捷 开 发 方法 的 创始 人 之 一 ， 现 为 
ThoughtWorks 公司 的 首席 科学 家 。 一 一 编者 注 

D 中 文 版 论文 请 参考 如 下 网 址 : http://www.cnblogs .com/cloudteng/archive/2012/02/25/2367565. 
html 。 一 -一 编者 注 
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Continuous Integration 


http://www.martinfowler.com/articles/continuousIntegration.html 


10.1.2 Jenkins 简介 


Jenkins 是 基于 Java 的 开源 CI 工具 ， 其 安装 和 操作 都 很 简单 。 另 外 ，Jenkins 不 仅 能 在 面板 
上 轻松 看 出 Job 成 功 或 失败 ， 还 可 以 借助 通知 功能 将 结果 以 邮件 或 RSS 订阅 的 形式 发 给 用 户 。 

除 此 之 外 ，Jenkins 还 允许 通过 插件 进行 功能 扩展 ， 所 需 功 能 可 以 随 用 随 添加 ， 而 且 还 支持 
主 从 式 集 群 ， 能 够 轻松 地 横向 扩展 。 

下 述 流 程 是 用 Jenkins 实现 持续 集成 的 一 个 例子 。 本 章 我 们 将 根据 下 述 流程 进 行 学 习 。 











e 为 Job 的 执行 制定 日 程 表 

。 签 出 源码 

e 通过 shell 脚本 执行 测试 (包括 检测 覆盖 率 ) 并 输出 结 
通过 shell 脚本 构建 文档 

。 统计 测试 结果 和 和 覆盖 率 

统计 TODO 

发 送 邮 件 通 知 Job 的 结 

e 将 Job 的 结果 保存 至 Slack 





10.2 Jenkins 的 安装 


RIIM Jenkins 的 安装 开始 学 习 。Jenkins 发 布 了 面 癌 Windows 和 OS X 的 安装 包 。 此 外 ， 还 
可 以 通过 包 管 理 帆 安装 Ubuntu/Debian, Red Hat/Fedora/CentOS、FreeBSD 等 。 我 们 可 以 根据 构建 
对 象 的 环境 选择 相应 的 版 本 。 本 书 将 以 Ubuntu 14.04. 上 的 安装 与 运行 为 基准 向 各 位 讲解 Jenkins。 


10.2.1 安装 Jenkins 主体 程序 
现在 来 安装 Jenkins HJ HERE -o AAT Parm SUIT apt 的 公共 密 钥 。 
$ wget -qg -0 - http://pkg.jenkins-ci.org/debian/jenkins-ci.org.key | sudo apt-key add - 
然后 打开 apt 的 设置 文件 /etc/aptsources.list， 将 下 述 语句 添加 到 最 后 一 行 。 


deb http://pkg.jenkins-ci.org/debian binary/ 
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最 后 执行 下 述 命令 ，Jenkins 就 会 被 安装 到 计算 机 中 。 


$ sudo apt-get update 
$ sudo apt-get install jenkins 


安装 完成 之 后 系统 会 日 动 生 成 jenkins HP, Jenkins 也 会 启动 。 比 如 启动 Jenkins KJAKI 4 
IP 地 址 为 10.0.0.1， 那 么 只 要 访问 http://10.0.0.1:8080 即 可 看 到 Jenkins 的 首页 。/var/ 
lib/jenkins 是 Jenkins 用 户 的 主 目录 ， 该 目录 下 保存 着 设置 文件 和 工作 目录 。 





NOTE 
Gunicorn, Tomcat 等 运行 着 Web 容器 的 环境 可 能 已 经 占用 了 8080 W0, RANA, 
Jenkins 无 法 在 默认 设置 状态 下 提供 服务 。 要 想 使 用 Jenkins， 必 须 更 改 Jenkins 启动 时 的 


HTTP 端口 号 ， 比 如 用 文本 编辑 器 打开 /etc/default/jenkins, 将 HTTP. PORT 的 值 从 默认 的 8080 
改 成 其 他 值 。 


10.2.2 本章 将 用 到 的 Jenkins 插件 


Jenkins 可 以 通过 插件 进行 功能 扩展 ， 因 此 广大 用 户 为 适应 各 种 用 途 开 发 了 大 量 插件 。 本 章 
我 们 将 用 到 下 述 4 个 插件 。 








(D Mercurial Plugin: 使 用 源码 管理 系统 (SCM ) Mercurial 时 所 和 需 的 插件 
(2) Cobertura Plugin: 生成 源码 覆盖 率 报 告 时 所 需 的 插件 

(3) Task Scanner Plugin: 统计 源码 中 的 TODO 时 所 需 的 插件 

(4) Slack Plugin: 用 来 回 Slack 发 送 通 知 的 插件 


搬 件 的 安装 可 以 通过 “系统 管理 ”界面 的 “管理 搬 件 ”进行 。 这 里 为 方便 说 明 ， 我 们 来 了 
解 一 下 通过 CLI( Command Line Interface， 命 令 行 接口 ) 进行 安装 EM 
首先 下 载 Jenkins 的 CLI 工具 。 


$ wget http://localhost:8080/jnlpJars/jenkins-cli.jar 





通过 CLI 工具 安装 搬 件 。 


$ java -jar jenkins-cli.jar -s http://localhost:8080 install-plugin tasks d 


mercurial slack cobertura 
重启 Jenkins， 使 刚 安 装 的 插件 生效 。 


$ sudo service jenkins restart 
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方便 好 用 的 Jenkins 插件 很 多 ， 除 了 这 里 介绍 的 几 种 以 外 ,还 有 JobConfigHistory Plugin, 
Email-ext Plugin, Timestamper Plugin, AERA 
下 面 是 这 些 插件 的 官方 维基 百科 。 





JobConfigHistory 
https://wiki.jenkins-ci.org/display/JENKINS/JobConfigHistory+Plugin 


Email-ext Plugin 
https://wiki.jenkins-ci.org/display/JENKINS/Email-ext+plugin 


Timestamper Plugin 
https://wiki.jenkins-ci.org/display/JENKINS/Timestamper 











10.3 ”执行 测试 代码 


现在 我 们 拿 一 个 简单 的 Python 项 目的 测试 代码 作为 例子 执行 一 下 。Python 项 目 由 版 本 控制 
系统 保存 ，Jenkins 将 从 版 本 控制 系统 获取 Python 项目 并 执行 测试 。 


10.3.1 让 Jenkins 运行 简单 的 测试 代码 
首先 ， 我 们 写 一 个 包含 unittest 模块 的 简单 的 测试 代码 ， 让 Jenkins 来 运行 它 ( LIST 10.1、 


LIST 10.2 ), 


© LIST 10.1 foo.py 


4 -*- coding:utf-8 -*- 


def divide(numi, num2): 
"n n 对 传 值 参数 做 除法 的 简单 函数 


return numi / num2 


© LIST 10.2 test foo.py 
4 -*- coding:utf-8 -*- 


import unittest 
ammpod TOG 


class SimpleTest (unittest.TestCase): 


" nn 测试 做 除法 的 函数 
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def test1 (self): 
self.assertEqual (foo.divide(2, 2), 1) 


def test2 (self): 


self.assertEqual(foo.divide(0, 1), 1) 


MEME. " maim "e 


unittest.main () 


将 这 两 个 文件 保存 在 Mercurial 的 版 本 库 里 ， 放 在 Jenkins 服务 器 上 的 /var/hg/simple test 目录 下 。 


10.3.2 RJA Job 


接 下 来 给 Jenkins 添加 Jobo Jenkins 的 Job 可 以 指定 多 种 类 型 的 任务 ， 比 如 构建 项 目 、 签 出 
代码 等 。 现 在 请 打开 Jenkins 面板 侧 边 菜单 的 “新 建 ” 界 面 ， 如 图 10.1。 





@® Jenkins 





Jenkins 


ew 新 建 pns 
& 用 广 AI + 
> 任务 历史 S W Name | 上 次 成 功 上 次 失败 上 次 持 绿 时 间 
P 系统 管理 " cafe 53 €» -#7 15 小 时 -如 25 €» © 
A Credentials " E. project 01 15 JE - 41 15 小 时 -后 24 毫秒 © 
构建 队列 一 | A» simple test 14 小 时 - #12 14 NIE - 41 0.95 35 © 
x 图 标 SML 
队列 中 没有 构建 任务 m8 国 Rss 部 国 RSS 失 败 pynss 
构建 执行 状态 一 
1 空闲 
2 空闲 








10.1 Jenkins 的 面板 


在 “新 建 ”界面 的 “Item 名 称 ” 处 输入 Job 名 ， 选 择 Job 种 类 。 如 图 10.2， 这 里 我 们 输入 
simple test 作为 Job 名 ， 种 类 则 选择 “构建 一 个 自由 风格 的 软件 项 目 ”， 然 后 点 击 界面 下 部 的 “OK” 
按钮 。 





@® Jenkins @ 
Jenkins 
S 新 建 tem 名 称 | simple tesi| 
& R^ @ 构建 一 个 自由 风格 的 软件 项 目 
D 任务 历史 这 是 Jenkins 的 主要 功能 .Jenkins 将 会 结合 任何 SCM 和 任何 构建 系统 来 构建 你 的 项 目 , 甚至 可 以 构建 软件 以 外 的 系统 
系统 管理 构建 一 个 maven 项 目 
£4 RILE 
构建 一 个 maven 项 目 .Jenkins 利 用 你 的 POM 文 件 ,这 样 可 以 大 大 减轻 构建 配置 . 
A Credentials 构建 一 个 多 配置 项 目 
适用 于 多 配置 项 目 ,例如 多 环境 测试 ,平台 指定 构建 ,等 等 . 
构建 队列 = 监控 一 个 外 部 的 任务 
队列 中 没有 构建 任务 这 个 类 型 的 任务 允许 你 记录 执行 在 外 部 Jenkins 的 任务 , 任务 甚至 运行 在 远程 机 器 上 .这 可 以 让 Jenkins 作 为 你 所 有 自动 构建 系统 的 控制 面板 .参阅 这 个 文档 查看 详细 内 容 . 
构建 执行 状态 一 
OK 
1 空闲 
2 空闲 








10.2 ”新建 界面 
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€ 指定 源码 管理 系统 
在 Job 设置 界面 的 “源码 管理 ”一 栏 中 选择 Mercurial， 随 后 会 显示 3 个 输入 框 ， 我 们 作 如 
下 输入 。 


(D Repository URL : 输入 版 本 库 的 URL 
输入 /var/hg/simple test 

(2 Branch: 输入 Mercurial 的 分 支 名 。 留 空 则 使 用 default 
这 次 我 们 要 用 的 是 default， 因 此 留 空 

O 源码 库 浏览 器 : 指定 用 于 查看 版 本 库 更 改 的 工具 
现 阶段 先 用 默认 的 “ 目 动 ” 





NOTE 
关于 版 本 库 pull 出 错 
Jenkins 的 Job 从 Mercurial 上 签 出 源码 时 ， 经 常 由 于 忘记 设置 版 本 库 权 限 而 导致 pull 
出 错 。 
安装 Jenkins 时 会 自动 创建 jenkins 用 户 ， 执 行 Job 的 都 是 这 个 用 户 ， 所 以 一 定 要 记得 给 这 
个 用 户 权 限 。 
另外 ， 有 时 即便 已 经 有 权限 ， 在 执行 hg pull 时 仍 会 遇 到 “不 可 信 的 用 户 ” “不 可 信 的 群 组 ” 
这 类 错误 。 这 种 情况 一 般 出 现在 版 本 库 的 “.hg/hgrc” 所 有 者 与 执行 hg 命令 的 用 户 不 一 致 的 时 
候 。 只 要 在 jenkins 用 户 的 $HOME/.hgrc 的 trusted 节 中 进行 设置 即 可 解决 该 问题 。 比 如 “不 
可 信 的 用 户 ” 为 foo、"“ 不 可 信 的 群 组 ”为 par 时 ， 则 需 在 hgrc 作 以 下 设置 。 
[trusted] 


user = foo 


group - bar 


LES, trusted 583 user, group 元 素 可 以 一 次 指定 多 个 值 ， 相 邻 两 值 之 间 用 逗号 隔 开 。 


€ 制定 日 程 表 

然后 我 们 来 设置 另 一 个 重要 项 目 构建 触发 需 。 这 个 项 目 能 像 cron 一 样 制定 日 程 表 ， 比 
如 让 Job 定期 执行 ， 或 者 在 其 他 Job 结束 后 执行 等 。 这 里 我 们 选择 “Build periodically”。 勾 选 之 
后 会 出 现 “ 日 程 表 ”输入 框 ， 我 们 在 这 里 设置 Job 的 执行 间隔 ， 具 体 方法 与 设置 crontab 时 一 
样 。 比 如 我 们 想 每 个 小 时 的 0 分 时 执行 Job， 则 写成 下 面 这 样 。 

















O * * * * 
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此 外 , 在 Jenkins 的 Job 设置 界面 里 ， -项 后 面 都 有 为 用 户 准备 的 帮助 。 各 位 如 末 遇 到 看 
不 仅 的 项 目 ， 可 以 点 击 相应 的 帮助 图 标 作 参考 。 


e 设置 执行 测试 代码 的 命令 
最 后 ， 在 “构建 ”选项 卡 处 设置 执行 测试 代码 的 命令 。 上 点击“ 增加 构建 步骤 ”之 后 即 可 选 
择 “Execute shell”。 然 后 在 文本 框 中 描述 下 述 命令 ， 如 图 10.3 所 示 。 





python test boo py 





构建 


Execute shell e 


Command python test foo.py 


See the list of available environment variables 











10.3 构建 步骤 “Execute shell" 


只 要 把 我 们 写 与 unittest 的 测试 用 例 时 手动 执 和 了 的 命 Hp 令 写 在 这 里 即 可 。 完 成 上 述 所 有 步骤 之 后 
点 击 “ 人 保存” 按钮 进行 保存 ， 接 下 来 Jenkins 将 在 我 们 指定 的 时 刻 执 行 Jobo 





10.3.3 Job 的 成 功 与 失败 


Jenkins 的 Job 可 以 从 管理 界面 手动 启动 。 现 在 我 们 试 着 点 击 面板 上 的 “立刻 构建 ”"”， 启 动 刚 
才 创 建 的 Job。 

随后 各 位 看 到 的 应 该 是 一 个 红色 图 标 ， 表 示 “ 失 败 ”。 我 们 可 以 点 击 左 侧 栏 “控制 台 输 出 ” 
链接 查看 执行 结果 ( 图 10.4 )。Jenkins 会 以 控制 台 日 志 的 形式 记录 每 次 执行 Job 的 过 程 ， 便 于 用 
户 调 查 失败 原因 。 

















Qu 控制 台 输 出 


Starte by user anon ymous 

Building in workspace /usr/shar Fp t6/.jenkins/jobs/simple test/works m 

$ /usr/bin/hg clone --rev default oupdate /var/hg/simple tes € /us r/sha e/t tomcat6/.jenkins/jobs/simple test/workspace 
adding changesets 

adding manifests 

adding file changes 

added 1 changesets wi 2 g to 2 files 

[workspace] $ /usr/bin/hg updat -rev defa 

2 files updated, 0 les merged, 0 files removed, 0 fil lved 
[workspace] $ /usr/bin/hg log V.~- templ {node} 

[workspace] $ /usr/bin/hg 1 : --rev plate (rev) 

[workspace] $ /usr/bin/hg lo -rev 249020 3804326727ttsla 4da5e7f9c46c80a4ed 
[workspace] $ /bin/sh -xe Jap tenete- tomcat6-tmp/hudsoni520743610171178519.sh 
* python test foo.py 

P 


mamtca ace m gu ce mcm se u Ge GR GE GR GG Né Me GG GE GM GM GR GR GR GE GE GR GS GG GR ME GE GR GG GM ME Ge uu m e e c re e m n c m e m m e e m m m m n m n gn rm o n n o m m 


R 2t 0.001 
FAILED us ilures-1) 
sro Exe ute shell' marked build as failure 


ep 
she di FAI LE 








图 10.4 通过 “控制 台 输 出 ”查看 Job 执行 失败 的 内 容 


从 日 志 


加 LIST 10.3 
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一 眼 就 能 看 出 测试 结果 为 FAILURE。 人 失败 的 原因 是 测试 代码 有 问题 ， 所 以 接 下 
来 ， 我 们 要 将 测试 用 例 修改 成 LIST 10.3 这 样 ， 然 后 重新 启动 Job. 


test foo.py 


4 -*- coding:utf-8 -*- 


import unittest 


import foo 


class SimpleTest (unittest.TestCase): 


"nm 测试 做 除法 的 PK ŽS 


ILIE 


def test1 (self): 


self.assertEqual (foo.divide(2, 2), 1) 


def test2(self): 


self.assertEqual(foo.divide(0, 1), 0) 


CRT 


三 三 " main M 


unittest.main() 








Q 控制 台 输出 


Started by user anonymous 

Building in workspace /usr/share/tomcat6/.jenkins/jobs/simple test/workspace 
[workspace] $ /usr/bin/hg showconfig paths.default 

[workspace] $ /usr/bin/hg pull --rev default 

pulling from /var/hg/simple test 

searching for changes 

adding changesets 

adding manifests 

adding file changes 

added 1 changesets with 1 changes to 1 files 

(run 'hg update' to get a working copy) 

[workspace] $ /usr/bin/hg update --clean --rev default 

1 files updated, 0 files merged, 0 files removed, 0 files unresolved 
[workspace] $ /usr/bin/hg log --rev . --template (node) 

[workspace] $ /usr/bin/hg log --rev . --template (rev) 

[workspace] $ /usr/bin/hg log --rev 673fllb2elbcca790f7fe93795d89ed642956ae3 


changeset: 0:673f1lb2elbc 

user: root 

date: Sat Aug 27 05:31:14 2016 +0800 
summary: add two py files 


[workspace] $ /usr/bin/hg log --template "«changeset node-'(node)' authors'[author|xmlescape)' rev='{rev}' date-'(date)'»«msg» 
(desc|xmlescape)«/msg»«added»(file adds|stringify|xmlescape)«/added»«deleted»[file dels|stringify|xmlescape)«/deleted»«files» 
[(files|stringify|xmlescape)«/files»«parents»(parents)«/parents»«/changeset»Mn" --rev "ancestors('default') and not 
ancestors(673fllb2elbcca790f7£e93795d89ed642956ae3)" --encoding UTF-8 --encodingmode replace 

[workspace] $ /bin/sh -xe /tmp/tomcat6-tomcat6-tmp/hudson828998221653588846.sh 


* python test foo.py 


Ran 2 tests in 0.000s 


OK 
Finished: SUCCESS 


10.5 ”执行 成 功 时 的 “控制 台 输 出 ” 


如 图 10.5， 这 次 看 到 的 应 该 是 蓝 色 图 标 ， 测 试 结果 为 SUCCESS, 
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10.4 测试 结果 输出 到 报告 


经 过 前 面 的 安装 与 设置 ， 我 们 已 经 可 以 用 Jenkins 创建 Job 并 执行 测试 代码 了 。 不 过 ， 实 际 
开发 中 的 测试 用 例 要 比 这 个 多 得 多 ， 而 且 单 纯 从 面板 上 查看 测试 成 功 /失败 并 不 能 满足 开发 的 
需求 。 

Jenkins 可 以 读 取 指定 格式 (xUnit 格式 ) 的 xml 文件 并 将 测试 结果 以 报告 形式 显示 在 屏幕 
上 。 使 用 Python 的 pytest 不仅 能 够 一 次 性 执行 多 个 测试 用 例 ， 还 能 将 结果 以 xUnit 格式 输出 。 
所 以 这 里 我 们 借助 pytest 来 输出 测试 结果 的 报告 。 





10.4.1 安装 pytest 
可 以 用 pip 2X Pytest。 


$ pip install pytest 


10.4.2. 调用 pytest 命令 


安装 完 pytest 后 就 可 以 调用 py .test 命令 了。 我 们 先 移 动 到 放 有 test foo.py 的 目录 下 ， 然 
后 执行 如 下 命令 。 


$ py Cest =--Junit-xml=test result snl 


该 命令 会 输出 一 个 xUnit 格式 的 test_result.xml 文件 。 现 在 只 要 让 Jenkins ZWE, RII 
能 从 屏幕 中 看 到 测试 结果 的 报告 了 。 


10.4.3 ”根据 pytest 更 改 Jenkins 的 设置 
首先 给 Jenkins 设置 virtualenv, Z pytest. 
sudo su - jenkins 


virtualenv .virtualenv/simple test 


source .virtualenv/simple test/bin/activate 


aUos Gs aUor SUr 


pip install pytest 


然后 来 更 改 Jenkins 的 设置 。 需 要 修改 的 只 有 “Execute shell” 中 指定 的 命令 行 操作 内 容 。 
原本 我 们 是 用 python 命令 直接 执行 unittest 的 测试 用 例 的 ， 这 里 替换 成 调用 上 面 提 到 的 
py .test 命令 ， 如 图 10.6. 
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构建 


Execute shell © 
Command . -/.virtualenv/simple test/bin/activate 


py.test --junit-xml-test result.xml 


See the list of available environment variables 





10.6 ”根据 pytest 修改 命令 





247 


接 下 来 设置 “构建 后 操作 ”选项 卡 ， 让 Jenkins 读 取 py .test 命令 输出 的 xml 文件 ， 如 图 


10.7。 


点 击 “增加 构建 后 操作 步骤 ”按钮 ， 选 择 “Publish JUnit test result report”。 随 后 该 选项 卡 
内 会 上 自动 生成 一 个 “Publish JUnit test result report” 表 格 项 ， 我 们 在 “测试 报告 (XML )” 里 指 


4E test result.xml. 








构建 后 操作 
Publish JUnit test result report e 
测试 报告 (XML) test result.xml 
Fileset 'includes' setting that specifies the generated raw XML report files, such as 'myproject/targettest-reports/" .xmi'. Basedir of the fileset is the workspace root. 
7 保留 长 的 标准 输出 /错误 © 
Health report amplification factor 1.0 e 


196 failing tests scores as 99% health. 5% failing tests scores as 95% health 








10.7 设置 读 取 测试 报告 


现在 再 点 击 “ 立 刻 构建 ”"， 则 将 显示 如 图 10.8 的 报告 。 


Test Result 





0 次 失败 
2 个 测试 
花 了 
IE 23) 54:5] 
所 有 的 测试 
Package 花 的 时 间 ”失败 (区 别 ) 跳 过 (区 别 ) Pass (区 别 ) 总 数 (区 别 ) 
test foo 0 毫秒 0 0 2 +2 2 +2 





10.8 测试 结果 报告 


10.5 ”显示 覆盖 率 报告 





现在 我 们 已 经 能 通过 Jenkins 界面 查看 测试 用 例 执行 结果 的 报告 了 。 接 下 来 我 们 看 看 如 何 用 


pytest-cov 获取 代码 的 履 盖 率 。 
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10.5.1 XX pytest-cov 





pytest-cov 同样 可 以 用 pip 安装 ， 具 体 如 下 。 
ocprpoaxnstall pyvtesb-cowv 


在 本 地 开发 环境 中 安装 完毕 后 ， 别 忘 了 在 Jenkins HJ virtualenv 环境 中 也 安装 一 遍 。 











10.5.2 ”从 pytest 获取 覆盖 率 
执行 下 述 命令 ， 输 出 xml m KI 
$ py.test --cov-foo --cov-report-xml 


报告 会 以 固定 名 称 coverage.xml 输出 到 当前 目录 下 。 如 采 想 同时 输出 xUnit 格式 的 文件 ， 则 
要 用 下 述 述 命 令 Oo 





$ py- test =-Junit-xml=test Tesult MM cn hos uoce 


然后 将 Jenkins 对 应 Job BJ. “Execute shell” 设 置 值 替换 成 上 述 命 令 。 


10.5.3 EREKE 


最 后 ， 让 Jenkins 读 取 上 述 命令 输出 的 xml FER TE BE EHI n] o 

点 击 “ 增 加 构建 后 操作 步骤 ”按钮 ， 选 择 “Publish CoberturaCoverage Report"。 随 后 该 选项 
EE 内 会 目 动 生成 一 个 “Publish Cobertura Coverage Report” 表 格 项 。 现 在 点 击 “ 高 级 ”按钮 ， 按 
照 下 述 方法 在 图 10.9 中 进行 设置 














e Cobertura xml report pattern : coverage.xml 


e Source Encoding : UTF-8 
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Publish Cobertura Coverage Report 


Cobertura xml report pattern coverage xml 


Consider only stable builds 

Fail builds if no reports 
Fail unhealthy builds E 
Fail unstable builds " 
Health auto update C 
Stability auto update C) 


Zoom coverage chart 


Maximum number of builds 


Source Encoding UTF-8 


Encoding when showing files. 
Coverage Metric Targets 


Methods 


Lines 


Conditionals 


For the PB and 





Unstable projects will be failed. 


Include only stable builds, i.e. exclude unstable and failed ones. 


fail builds if No coverage reports are found. 


Unhealthy projects will be failed. 


Auto update threshold for health on successful build. 


Auto update threshold for stability on successful build. 


bia 


*» 


4» 


Configure health reporting thresholds. 
For the row, leave blank to use the default value (i.e. 80). 


rows, leave blank to use the default values (i.e. 0). 


Zoom the coverage chart and crop area below the minimum and above the maximum coverage of the past reports. 


Only graph the most recent N builds in the coverage chart, 0 disables the limit. 


80.0 Pæ 0.0 
80.0 Aæ 0.0 
70.0 Pa 0.0 


This is a file name pattern that can be used to locate the cobertura xmi report files (for example with Maven2 use **/target/site/cobertura/coverage.xml). The path is relative 
to the module root unless you have configured your SCM with multiple modules, in which case it is relative to the workspace root. Note that the module root is SCM-specific, 

and may not be the same as the workspace root. 
Cobertura must be configured to generate XML reports for this plugin to function. 
NOTE: If concurrent builds are enabled for this job, and a later build finishes before an earlier build, the later build will reduce or skip trend analysis/charting. 


*» 


0.0 


0.0 


0.0 





10.9 
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设 定 完成 之 后 执行 Job， 接 下 来 各 位 应 该 能 在 屏蔽 上 看 到 如 图 10.10 RRR mIRE T o 


Code Coverage 


Cobertura Coverage Report 














Trend 
Packages 100% 
Files 100% 
Classes 100% 
Lines 100% 
Conditionals 100% 
Project Coverage summary 
Name Packages Files 
Cobertura Coverage Report 100% | 1/1 100% | 1/1 
Coverage Breakdown by Package 
| Name | Files | Classes 
= 100% 11 10095 1A 


10.10 





Classes Lines Conditionals 
100% | 11 100% | 22 100% | 0/0 
| Lines Conditionals 
100% 2/2 N/A 


覆盖 率 报告 


测试 履 兰 到 的 源码 行 显示 为 绿色 ， 反 之 显示 为 粉红 色 。 
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Code Coverage 


Cobertura Coverage Report >. > 





foo.py 


Trend 


4O A: 














File Coverage summary 
Name Classes Lines Conditionals 


foo.py 100% 11 100% | 2/2 10096 0/0 


Coverage Breakdown by Class 





Name Lines Conditionals 


foo.py 100% 2/2 N/A 


3 l def divide(numl, num2): 
"" "对 传 值 参数 做 除法 的 简单 函数 。 








10.11 查看 各 个 文件 的 覆盖 率 


如 图 10.11， 这 样 一 来 我 们 就 能 掌握 执行 测试 代码 之 后 的 履 盖 率 了 。 接 下 来 我 们 将 学 习 
Django 测试 代码 的 执行 方法 。 





10.6 ”执行 Django 的 测试 





前 面 我 们 学 习 了 涉及 到 unittest 和 pytest 的 测试 代码 的 执行 方法 ， 这 里 我 们 学 习 一 下 如 何 执 
£T Django 的 测试 。Django 有 着 专用 的 测试 机 制 ， 各 位 在 采用 Django A UER S ALESTEU S 
考 。 在 学 习 如 何 执 行 测试 的 同时 ， 我 们 还 会 学 习 如 何 向 邮箱 、Slack 等 发 送 通知 。 








10.6.1 安装 Python 模块 
这 里 要 安装 Django 主体 程序 以 及 Django 与 Jenkins 进行 联动 时 所 需 的 儿 个 工具 。 


e Django 主体 程序 
首先 安装 Django 主体 程序 。 


$ pip install django 


( unittest-xml-reporting 
我 们 知道 ， 要 想 让 Jenkins 显示 测试 结果 报告 ， 需 要 将 测试 执行 结 来 以 Junit 格式 的 xml X. 
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件 形式 输出 。 

使 用 Django 的 manage .py test 命令 执行 测试 后 ， 生 成 的 结果 只 是 纯 文本 ， 并 不 满足 上 
述 格式 要 求 。 用 unittest-xml-reporting 可 以 解决 这 一 问题 ， 其 安装 如 下 。 


b] AS 











$ pip install unittest-xml-reporting 


@ coverage 
还 要 安装 coverage 模块 。 


$ pip install coverage 
10.6.2 Django 的 调整 


e 创建 项 目 目录 
创建 项 目 目录 。 这 里 我 们 用 cafe/apps 作为 其 名 称 。 


$ mkdir cafe 


S cd cafe 


$ django-admin.py startproject apps 


这 个 项 目 由 Mercurial 的 版 本 库 管 理 ， 保 存在 /var/hg/cafe 目录 下 。 
e 创建 Django 应 用 








接 下 来 创建 Django 应 用 。 运 行 上 面 那 条 命令 之 后 ， 我 们 会 得 到 apps 目录 。 现 在 移动 到 该 
目录 下 ， 创 建 一 个 名 为 menu 的 应 用 。 


S Gd apps 


$ python manage.py startapp menu 


执行 完毕 后 将 生成 apps/menu 目录 。 


10.6(.3 示例 代码 


@ 编写 模型 
编写 模型 。 我 们 这 里 所 用 的 概念 是 一 间 咖 啡 厅 的 茶 品 清单 ， 代 码 如 LIST 10.4 所 示 。 


© LIST 10.4 cafe/apps/menu/models.py 
4 -*- coding:utf-8 -*- 


from django.db import models 
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TEA KINDS ( 
("english", u" RAIZ "), 


: + 
("chinese", u" 中 国 茶 ") ， 


("japanese", u" 日 本 茶 noe 


class TeaManager (models.Manager): 
def recommended(self): 
"nnm 仅 显 示 推 荐 次 T "nnn 


return gelf, eum cabo Mec 


det coumt each kine scl t 
""" 以 字典 形式 返回 各 类 茶 的 件数 "rn. 
aes = gelf, vyalues list ("kine") e eme Ere ES | 
count -node MCST me 


CelbspmIedectebesulit) 


class Tea(models.Model): 


objects - TeaManager() 


name 


kinel 


models.CharField(u" 4T", max length-255) 


models.CharField(u" fh2$ ", max length-255, choices-TEA KINDS) 
price = models.IntegerField (u" 价格 ") 
is recommended = models.BooleanField ( 


u" 推荐 两 品 "，default=False) 


€) 编写 表单 
表单 代码 如 LIST 10.5 所 示 。 


© LIST 10.5 cafe/apps/menu/forms.py 


4 -*- coding:utf-8 -*- 


from django import forms 
from menu.models import Tea, TEA KINDS 


class TeaSearchForm(forms.Form): 
neme = forms. Charriele(label=su"", max length=255, recuired=ralse) 
kind = forms.MultipleChoiceField( 


label-u" fh2$ ", choices-TEA KINDS, required-False) 


ektre report = TOMS. BOOoleemt Lele 


label-u" 输出 追加 报告 "，required=False) 


def clean(self): 
elne! 


= gelr 


yeaneenelaee 


LE mE gelr, 二 局 Valic(): 


if not clnd["name"] 


return clnd 


€ [5] settings.lINSTALLED. APPS 添加 menu 


return eclnd 


rase Lorms.valudatrouEtrcr( 
un 名 称 和 种 类 请 至 少 输入 一 项 ") 


Se ln ne 
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创建 完 menu 应 用 后 记得 在 settings.py AJ INSTALLED APPS 里 指定 它 (LIST 10.6). sb 


这 一 步 是 不 能 用 manage.py 执行 测试 的 。 


© LIST 10.6 cafe/apps/settings.py 


INSTALLED APPS = ( 


Jengo 
1G 可 有 so ， 
wollen 
angok 
'django. 
'ejango. 


'menu'!, 


coni 1b 


conl tabs 


CONTATO 


comertor 
contrbib. 


conisrzdbs: 


admin', 


aub 


S oretgue guise scm 


Sessions', 
Messages 


STAC LCELLGS! , 


€ 7j Jenkins 4 settings 
我 们 希望 Jenkins 利用 unittest-xml-reporting 将 测试 结果 以 xml 文件 的 形式 输出 ， 所 以 这 里 

要 专门 为 Jenkins 写 一 个 settings。 
代码 如 LIST 10.7 所 示 。 


© LIST 10.7 cafe/apps/settings jenkins.py 


4 -*- coding:utf-8 -*- 


from settings import * 


UnHHdHHdHHdHHHSJHHSHHH S GN 
# Xml test runner 


THEHEIHHEHBEHERHEHHHEHBE HH BE ERG 


TEST RUNNER 


'xmlrunner.extra.djangotestrunner.XMLTestRunner' 
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PEST QUTPUT DIR > "testereports 


DATABASES - | 
'default': ( 
'ENGINE': 'django.db.backends.sqlite3', 
'NAME': 'jenkins.db', 
USERI EEO 
"PASSWORD! t 
iOS 
DECR QU 


@ 生成 迁移 文件 
前 面 我 们 用 示例 代码 创建 了 模型 ， 所 以 这 里 还 需要 生成 迁移 文件 。 移 动 到 manage.py 文件 
所 在 的 目录 下 执行 下 述 命令 ， 即 可 完成 迁移 文件 的 生成 。 











$ python manage.py makemigrations 


© 编写 测试 代码 
模型 和 表单 的 代码 都 已 经 写 好 ， 接 下 来 该 编写 测试 代码 了 。 测 试 代码 如 LIST 10.8 所 示 。 








© LIST 10.8 cafe/apps/menu/tests.py 


4 -*- coding:utf-8 -*- 
import unittest 


from django.test import TestCase as DjangoTest 


from menu.models import Tea 


from menu.forms import TeaSearchForm 
Low = amca hes cre (sli(L[0l, x)) EGr x Lm Dlls)) 


class TeaManagerTest (DjangoTest): 


def setUp(self): 


datas = ( 
(Qalamie up act 
(u" KAzl$", "english"), 
(u" $2252] 7E ", "english"), 
(un 马龙 茶 ", "chinese"), 
(un 铁 观音 "，"chinese" ) ， 
(u" 普洱 茶 ", "chinese"), 
( 


u" FINES D "japanese" ) , 
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for data in row (datas): 


Tea.objects.create(price-100, **data) 


cet test (eum (EXON. kinci (self) s 
pes = Tea. eges count each kinel) 


self.assertEqual(result, dict(english-2, chinese-3, japanese-1)) 


class TeaSearchFormTest (unittest.TestCase): 
ccc c E 
"n" 检查 输入 正音 时 是 否 会 报错 UC 
params -codsxcetiname-"too"» kgnd-["englrsh*] 
form - TeaSearchForm(params) 


seli assensus (torm. is valici(), True, COrm.errore.@6 Text) ) 


cef test ertneri (sellrt) a 
nin 检查 名 称 和 种 类 都 无 输入 时 是 否 会 报错 ""。 
params = dict () 
form = TeaSearchForm(params) 


seli assertEgqual (torm. is valic(), False, Torm. errors.@68 Cet) ) 


cef ccc mem (selt) s 
nn 检查 输入 名 称 后 是 否 会 报错 nn 
emamesee ene neme ieee 
form = TeaSearchForm(params) 


seli assertigual (torm. is valici(), True, Orm. errore. a6 TEKEL) ) 


cef test either (Lets) s 
nn 检查 输入 种 类 后 是 否 会 报错 rrr 
params = dict (kind=["english", "chinese"]) 
form = TeaSearchForm(params) 


selt curse ui (Torm. is valic(), True, Orm. errorS. aS TExE l) ) 


10.6.4 Jenkins 的 调整 


e 新 建 Job 
点 击 Jenkins 面板 侧 边栏 的 “新 建 ”>， 创 建 Job. 


由 选择 “构建 一 个 自由 风格 的 软件 项 目 ” 
QE "Item 名 称 ” 处 输入 cafe( Job 名 并 没有 人 硬性 要 求 ， 这 里 只 是 特意 选择 了 与 项 目 名 称 相 
同 的 cafe ) 








@ “源码 管理 系统 ”的 设置 
这 里 使 用 Mercurial。 我 们 事先 已 经 将 cafe 的 版 本 库 放 在 了 /var/hg/cafe 下 ， 所 以 直接 在 
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Jenkins 的 设置 界面 作 如 下 输入 即 可 。 


e 源 公 管理 系统 : Mercurial 

e Repository URL : /var/hg/cafe 
e Branch : default 

e i PEDI sS: Auto 


€ TE Execute shell 中 填写 测试 命令 
把 Django 测试 结束 后 输出 覆盖 率 报 告 的 命令 写 在 “Execute shell” 中 。 如 果 只 是 单纯 地 进 
行 Django 测试 ， 可 以 用 下 述 命令 执行 。 





$ PYTHONPATH=apps python -m manage test menu --settings=settings jenkins 


通过 coverage 命令 执行 上 述 代 码 即 可 获取 覆盖 率 。 接 下 来 ， 我 们 将 上 述 代码 改 成 下 面 这样 。 





$ PYTHONPATH-apps coverage run --source-apps -m manage test menu --settings-s 


ettings jenkins && coverage xml -o coverage reports/coverage.xml 


然后 ，run 成 功 之 后 ， 执 行 coverage xml 命令 即 可 输出 xml 格式 的 报告 
这 里 我 们 指定 了 --source-apps 选项 。 PT 日 定 的 目录 下 。 在 
过 到 这 种 Django 项 目 目录 与 版 本 库 路 径 不 一 致 的 情况 时 ， 指 定 该 选项 能 有 效 防 止 读 取 无 关 人 代码。 








不 要 直接 在 Django! 的 项 目 目录 下 执行 测试 

获取 覆盖 率 时 有 一 点 需要 注意 ， 那 就 是 不 ou. Django 的 项 目 目录 下 执行 测试 。 使 用 
Django 时 有 很 多 工作 是 在 Django 的 项 目 目录 下 进行 ( 比如 上 面 例子 中 移动 到 apps 目录 下 并 执 
何 manage py test), ADS Rd bx Tu 率 ， 那 么 一 旦 我 们 移动 到 apps 并 执行 
manage.py test， 会 连同 Django 本 身 一 同 测试 并 统计 履 盖 率 ， 最 终 的 报告 会 变 成 图 10.12 这 
个 样子 。 因 此 ， 为 了 防止 非 测 试 对 象 混 入 覆盖 率 报告 ， 必 须 对 这 一 点 强加 注意 。 


Project Coverage summary 

Name Packages Files Classes Lines Conditionals 
Cobertura Coverage Report 100% 64/64 100% 308/308 100% 308/308 39% | 15901/40578 100% 0/0 
Coverage Breakdown by Package 


Name Files Classes Lines Conditionals 
100% 1⁄1 100% 1⁄1 54% 240/444 N/A 





100% 11 100% 11 100% 14/14 N/A 





100% 3/3 100% 3/3 78% 193/249 N/A 





197/230 N/A 





jango.conf.locale 100% 1⁄1 100% 11 100% 2/2 N/A 





k 

k 
rtualenv.cafe.lib.python2.7.site-packages.django.aops 

k 

k 

k 























IC_ i CC (ex e 
e 
N 
e 
e 
n 
N 
co 


jango.conf.urls 100% 11 100% 11 30% 13/44 N/A 





图 10.12 混入 多 余 代码 之 后 的 覆盖 率 
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10.6.5 “构建 后 操作 ”选项 卡 的 设置 

“构建 后 操作 ”选项 卡 里 设置 的 任务 将 在 Job 的 构建 处 理 执行 完毕 后 执行 。 

Jenkins 读 取 测 试 结果 报告 与 覆盖 率 报告 的 操作 需要 在 这 里 进行 设置 。 另 外 ， 执 行 Job 失败 
的 邮件 通知 也 是 在 这 里 设置 的 。 














图 读 取 测 试 结果 报 告 

"Publish JUnit test result report” 中 有 “测试 报告 ( XML )” 一 项 ， 用 于 指定 输出 的 xml 
Ts 

这 里 允许 使 用 通配符 。unittest-xml-reporting 会 针对 每 一 个 测试 类 输出 一 个 xml 文件 ， 所 以 
按照 下 述 方法 设置 即 可 。 为 外 ， 测 试 结 来 的 输出 目录 要 与 Jenkins 的 settings 中 指定 的 目录 一 致 。 








e 测试 报告 (XML ) 


cafe/test reports/*.xml 


€) 读 取 覆盖 率 报告 
"Publish CoberturaCoverage Report” 里 有 “Cobertura xml report pattern”， 我 们 要 在 这 里 指定 
coverage xml 命令 输出 的 文件 。 


e Cobertura xml report pattern 


cafe/coverage reports/*.xml 


e 查看 结果 
上 述 设 置 完成 之 后 ， 我 们 就 可 以 看 到 测试 结果 报告 和 履 盖 率 报告 了 ， 如 图 10.13 和 图 
10.14, 








Test Result 
0 次 失败 (+0) 
5 个 测试 (+0) 
花 了 
所 有 的 测试 
Package 花 的 时 间 “失败 (区 别 ) 跳 过 (区 别 ) Pass (区别) 总 数 {区别 ) 
menu.tests 4 毫秒 0 0 5 5 











10.43 测试 结果 报告 


258 | 第 2 部 分 团队 开发 的 周期 





Code Coverage 


Cobertura Coverage Report 


Trend 


Packages 
Files 
Classes 
Lines 


Conditionals 100% 


Project Coverage summary 


Name Packages Files 

















Classes Lines Conditionals 
Cobertura Coverage Report 100% 4/4 44% 8/18 44% 8/18 54% 91/168 100% 0/0 
Coverage Breakdown by Package 

Name Files Classes Lines Conditionals 
apps 50% 12 50% 1⁄2 41% 747 N/A 
apps.apps 4096 2/5 4095 2/5 47% 22/47 N/A 
apps.menu 40% 40 4096 40 5795 56/98 N/A 
apps.menu.migrations 10096 1A 100% 1A 100% 6/6 N/A 








图 10.14 ERRE 


NOTE 


输出 代码 覆盖 率 报告 时 可 能 会 出 现 乱码 ， 这 是 Java 字体 设置 导致 的 。 解 决 中 文 乱码 的 方法 


。 Linux 





HU gIEZMBEaPRER export JAVA TOOL. OPTIONS-z'-Dfile.encoding-UTF-8" 
- Windows 


新 建 变 量 JAVA TOOL OPTIONS , value 值 为 -Dfile.encoding=UTF-8 
重启 Jenkins 之 后 再 执行 一 遍 刚 刚 出 现 乱码 的 Job， 可 以 看 到 乱码 问题 已 经 被 解决 。 





@ 邮件 通知 


"E-mail Notification” 中 有 “Recipients”， 我 们 要 在 这 里 指定 通知 接收 方 的 邮箱 地 址 ， 如 图 
10.15 所 示 。 





E-mail Notification 


© 
Recipients | projectml@beproudjp 


Whitespace-separated list of recipient addresses. May reference build parameters like $PARAM. E-mail will be sent when a build fails, becomes unstable or returns to stable. 


每 次 不 稳定 的 构建 都 发 送 邮件 通知 
单独 发 送 邮 件 给 对 构建 造成 不 良 影响 的 责任 人 











图 10.15 设置 收 件 人 


除 此 之 外 ， 还 要 在 侧 边 栏 “ 系 统管 理 ” 一 “系统 设置 ”里 找 出 “Jenkins Location", 在 “ 系 
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统管 理 员 邮件 地 址 ”中 填写 Jenkins 用 来 发 送 邮 件 的 邮箱 地 址 ， 然 后 在 “E-mail Notification” PF 
的 “SMTP 服务 器 ”中 设置 SMPT 服务 器 (图 10.16、 图 10.17 )。 另 外 ， 如 果 要 使 用 Gmail 等 需 
要 认证 的 邮箱 账户 ， 需 要 点 击 “E-mail Notification” 中 的 “高 级 ”按钮 ， 指 定 “ 用 户 名 ”“ 密 
I3" SERE. 








Jenkins Location 


Jenkins URL http://bpbook.beproud.jp:8080/ e 





系统 管理 员 邮 件 地 址 jenkins <jenkins@beproud.jp> e 





10.46 设置 发 件 人 的 邮箱 地 址 





邮件 通知 
SMTP 服 务 器 10.0.0.1 e 


RIP REUS EIS © 





mig... 


ul 





10.17 设置 发 件 人 的 邮箱 服务 器 
在 上 述 设 置 完成 之 后 ，Jenkins 会 在 Job 执行 失败 时 发 送 邮 件 ， 以 通知 开发 者 。 


NOTE 


安装 插件 后 还 可 以 向 即将 讲 到 的 Slack, IRC, Jabber, Growl 等 发 送 通 知 。 另 外 ， 安 装 
Email-ext plugin 之 后 还 可 以 对 邮件 的 主题 、 正 文 、 通 知 设置 等 进行 自 定 义 。 


图 向 Slack 发 送 通 知 

Slack 是 一 款 可 以 器 平台 使 用 的 团队 交流 工具 ， 还 可 以 与 许多 第 三 方 服务 集成 。Jenkins 可 
以 借助 Slack Plugin [5] Slack 发 送 通 知 。Slack 的 相关 说 明 请 参考 4.3 节 。 

首先 进行 Slack 的 设置 。 找 出 需要 通知 的 频道 或 组 ， 选 择 “Add a service integration”， 添 加 
"Jenkins CI”。 接 下 来 会 跳 转 到 “Post to Channel” 界 面 ， 确 认 要 通知 的 频道 或 组 无 误 后 ， 点 击 
"Add Jenkins CI Integration” 按 钮 ， 跳 转 至 目 定 义 界 面 。 这 里 要 先 将 “Step 3” 中 写 的 
“TeamDomain” 和 “Integration Token” 复 制 下 来 ， 因 为 后 面 设置 Jenkins 时 会 用 到 。Slack 发 送 

通知 时 所 用 的 名 字 和 头像 可 以 在 这 个 界面 修改 。 最 后 点 击 “Save Setting” 完 成 Slack 的 设置 。 

接 下 来 设置 Jenkins。 在 Jenkins 的 “系统 管理 ”一 “系统 放置 ”中 找到 “Global Slack 

Notifier Settings”， 然 后 作 如 下 更 改 (图 10.18 )。 


(D TeamDomain: 设置 Slack 时 复制 的 TeamDomain 
(2) Integration Token: 设置 Slack 时 复制 的 Integration Token 
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(3) Channel: Slack 的 频道 名 或 组 名 
(4) Build Server URL: Jenkins 服务 器 的 URL 





Global Slack Notifier Settings 


Team Domain 


beproud e 
Integration Token HCZODgqnayRPHBMJJyNKIR3P © 
Channel slack_test 
Build Server URL http://bpbook.beproud.jp:8080/ 9 








10.18 Global Slack Notifier Settings 示例 


接着 在 Job 的 设置 中 找到 “Slack Notifications”， 人 勾 选 要 通知 的 项 目 ， 最 后 在 “构建 后 操作 ” 
处 选择 添加 Slack Notifications” 即 可 (网 10.19 )。 


Slack Notifications 


Notify Build Start 
Notify Aborted 
Notify Failure 
Notify Not Built 
Notify Success 
Notify Unstable 
Notify Back To Normal 


Notify Repeated Failure 
Include Test Summary 


了 Include Custom Message 
Show Commit List with Titles and Authors 


Team Domain 








e 

Integration Token e 

Project Channel slack test e 
Test Connection 

关闭 构建 (重新 开启 构建 前 不 允许 进行 新 的 构建 ) © 

在 必要 的 时 候 并 发 构建 © 


10.19 通知 项 目 示例 


现在 再 执行 Job WEN Slack 发 送 通 知 了 (图 10.20 )。 








Em jenkins 


| sample test -#13 Started by user anonymous (Open) 





| sample test -#13 Starting... after 1.7 秒 and counting (Open) 





10.20 向 Slack 发 送 通 知 


10.7 通过 Jenkins 构建 文档 


我 们 在 第 7 章 中 介绍 了 如 何 用 Sphinx 写 文档 ， 现 在 来 看 看 如 何 用 Jenkins 来 辅助 Sphinx 编 
号 文档 。 
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用 Sphinx 编写 文档 时 经 常会 遇 到 下 述 问题 。 


e reST 语法 错误 
e 起 记 提 交 文 档 中 引用 的 图 片 或 源码 





如 果 存 在 上 述 问题 ，Sphinx 会 在 执行 构建 命令 时 发 出 警告 。 因 此 ， 只 要 我 们 利用 Jenkins 定 
期 监视 文档 的 构建 ， 就 能 尽早 发 现 这 些 问 题 。 
本 书 就 是 借助 Sphinx 编写 的 。 接 下 来 我 们 将 以 本 书 的 编写 过 程 为 例 ， 学 习 -一 下 我 们 应 该 怎 


样 用 Jenkins 管理 多 人 共同 执笔 的 书稿 。 该 方法 不 仅 适 用 于 多 人 共同 管理 文档 的 情况 ， 对 单独 管 
理 文 档 的 情况 也 有 一 定 的 帮助 。 











10.7.1 eX Sphinx 
首先 将 Sphinx 安装 到 本 地 环境 中 。 


SLS ngEell ep 3n» 


10.7.2 在 Jenkins 添加 Job 
该 Job 的 设置 如 下 ( /var/hg/bpbook 为 源码 版 本 库 )。 


(D 基本 设置 
e Job 类 型 : 目 由 风格 
e Job 名 称 : bpbook 
D 源码 管理 系统 
e SCM : Mercurial 
e 版 本 库 : /var/hg/bpbook 
e 分 文 : default 
(30 构建 触发 需 
e 种 类 : 定期 执行 
e 日 程 表 : H/15**** ( 每 小 时 的 15 分 ) 


10.7.8 Sphinx 构建 发 出 警告 时 令 Job 失败 


Sphinx 的 -w 选项 可 以 将 敬告 内 容 以 文件 形式 输出 。 我 们 希望 出 现 营 告 时 让 Jenkins 的 Job 
失败 ， 所 以 要 在 “Execute shell” 选 项 卡 人 处 进行 如 下 设置 当 输出 警告 内 容 的 文件 不 为 空 时 ， 用 
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返回 码 9 结束 执行 。 


Snanme lo mE -=w build warnings. souboc docs 


lE | -8 buile warnings txt | ; Cnem 
exit 9 


iz aL 


这 里 的 返回 码 可 以 用 0 之 外 的 任意 数字 。Jenkins 将 所 有 构建 完毕 时 返回 码 不 为 0 的 Job 25 
视 为 失败 。 另 外 ， 为 保证 每 次 都 重新 构建 所 有 文档 ， 要 加 上 -a -E 选项 。 








10.7.4 查看 成 果 


Jenkins 可 以 在 管理 界面 查看 工作 区 内 的 文件 ， 因 此 我 们 可 以 在 这 里 查看 Job 构建 的 文档 
(图 10.21 )。 





Workspace of bpbook on master 


E e 























ia 
a. 
= 
o 
o 
o 
" 














genindex.html 2.58 KB 查看 
index.html 3.76 KB 查看 



































10.21 查看 工作 区 


Jenkins 中 的 各 Job 首页 的 “描述 ”中 人 允许 添加 html 标签 ， 我 们 可 以 将 已 构建 的 文档 的 链接 
搬入 “描述 ”中 ， 这 样 一 来 就 能 下 接 从 首页 点 击 链接 查看 构建 后 的 文档 了 ( 图 10.22), 
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Project bpbook 


构建 完成 .html 
构建 完成 .pdf 


禁用 项 目 


相关 连接 


* Last build(411),8 分 37 秒 之 前 

* Last stable build(411),8 分 37 秒 之 前 

* Last successful build(411),8 分 37 秒 之 前 
* Last failed build(4/6),38 分 之 前 

* Last unsuccessful build(46),38 4j 7 Bi 














10.22 ”编辑 Job 首页 的 “描述 ” 


10.7.5 通过 Task Scanner Plugin 管理 TODO 





Zi SARAR, AL T e 4 — 2e Fs] AE RI EP a PST AP a e UT JD TODO 注释 的 形 
式 记 录 下 来 。 用 Jenkins 的 Task Scanner Plugin 插件 可 以 让 我 们 在 报告 中 看 到 TODO 注释 (网 10.23 ). 





Open Tasks 
Open Tasks Trend 


All Open Tasks New Tasks Fixed Tasks 


23 1 1 


Summary 


Total High Priority Normal Priority 
23 0 23 


Details 
-Folders Files | Open Tasks || Details 


File Total Distribution 
authors.rst 
guestbook-project.rst 
index.rst 





index.rst 





index.rst 

template and rules.rst 
todolist.rst 

Total 





N = m oOo-—0o0-2-— 








10.23 Task Scanner Plugin 报告 


如 图 10.24 所 示 ， 报 告 中 还 对 对 应 行 做 了 高 亮 处理 。 





168 . 。todo: :根据 sphinx-1l.3 的 发 布 情况 更 新 版 本 显示 


170 . 。 安装 流程 请 参考 日 本 sphinx 社 区 Sphinx-users .jp 运营 的 网 站 (http://sphinx-users .jp/) 











10.24 ”高 亮 显示 
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Zh. Sphinx 扩展 中 有 一 个 todo 扩展 ， 激 活 之 后 即 可 人 允许 用 户 使 用 todo 指令 (图 10.25 )。 
todo 指令 的 布局 与 note 和 warning 相同 。 





Todo: 根据 Sphinx-1.3 的 发 布 情况 更 新 版 本 显示 








10.25 ”使 用 todo 指令 的 示例 


与 其 他 人 合 著 一 本 书 时 ， 我 们 常会 怀疑 上 自己 写 的 内 容 与 其 他 章 市 是 否 存 在 了 矛盾， 或 是 目 己 
写 的 稿子 是 否 满足 与 合 著者 之 间 定 下 的 规则 。 如 采 每 出 现 一 次 这 种 情况 就 俘 下 手 去 检查 一 过 ， 
势必 拖累 稳 子 的 进度 ， 所 以 我 们 选择 先 留 下 TODO 注释 ， 等 竺 最 后 统一 解决 。 

KIR, TODO 注释 经 常 写 了 不 删 ， 让 人 摘 不 清 到 底 问题 有 没有 解决 。 这 种 情况 不 仅 存在 于 
写 稿 的 过 程 中 ， 在 敲 代 人 码 时 也 同样 会 发 生 。 虽 然 每 次 处 理 完 源 但 或 稿件 都 手动 grep 搜索 TODO 
注释 能 避免 这 种 情况 发 生 ， 但 实在 太 肪 烦 了 。 

此 ， 在 用 Jenkins 执行 测试 或 构建 文档 时 ， 可 以 顺便 生成 一 个 TODO 的 列表 。 另 外 ，Task 
Scanner Plugin 能 够 用 图 表 显 示 TODO 注释 的 数量 。 随 肴 TODO 被 一 个 个 解决 ， 我 们 能 够 耳 观 
地 敬 握 其 减少 的 过 程 。 看 到 TODO 减少 能 够 激发 开发 者 解决 TODO 的 积极 性 ， 在 某 种 意义 上 起 
到 提高 效率 的 作用 。 
























































10.7.6 Task Scanner Plugin 的 设置 示例 


首先 从 “管理 插件 ”安装 Task Scanner Plugin。 完 成 后 ，Job 设置 界面 的 “构建 后 操作 ” 选 
项 卡 处 会 增加 “Scan workspace for open tasks” 一 项 。 匀 选 该 项 ， 输 入 下 述 几 项 。 


e Files to scan: TODO 的 搜索 对 象 
e Files to exclude: 这 里 设置 的 对 象 将 不 包含 在 搜索 范围 内 
e Tasks tags: 这 里 输入 的 字符 串 将 被 视 为 TODO， 计 入 统计 结果 





管理 本 书稿 的 Job 就 是 按照 图 10.26 设置 的 。 
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构建 后 操作 
Scan workspace for open tasks @ 
Files to scan **/* rst 
rkspace h as ** p pi asedir 
is set, th used 
Files to lud 
Se! setting that speci space fi cal g k So Bi 
Tasks tags High priority Normal priority Low priority 
XXX TODO, FIXME 

Config ig: ld be lo: workspi p y a ci gs co: ied, e.g. TODO, FIXME, Only 

alphani iow se f'eSSIO! ISSI ant to control the ri ression 

your o 
Ignore case 

Ignore the case g 
Regul p 

eat the ta iS regul: hat the regular expression must con g group: ig Seco 

message. An example of such a regular expression would be '^.*(TODO(?:[0-8]*))(.*)$" 

Example Text 
mess icanned foi ks ed ab 
mi... 








10.26 Task Scanner Plugin 设置 示例 


10.8 Jenkins 进 阶 技巧 


10.8.1 好 用 的 功能 
这 里 简单 了 解 一 下 前 面 没 有 讲 到 的 Jenkins 的 好 用 功能 。 


@ Job 触发 器 
Job 触发 硕 是 指 通过 Jenkins 的 某 个 Job 来 启动 其 他 Job 的 功能 。 它 没有 专门 的 设置 界面 ， 
必须 到 “构建 触发 需 ” 的 “Build after other projects are built” 或 “构建 后 操作 ”的 “Build other 








projects” 中 进行 设置 。 
这 里 可 以 设置 前 一 个 Job 失败 时 不 执行 后 续 Job， 因 此 能 够 构成 “测试 不 通过 则 不 进行 部 
署 ”的 工作 流程 。 





e Ripe 

用 户 管理 可 以 设置 Jenkins BA ESTA n], REAREA, HEEL B PISA bà 
可 通过 外 部 网 络 访问 Jenkins， 或 者 只 有 管理 员 能 够 执行 Job, F, 

另外 ， 用 户 管 理 后 端 可 以 使 用 LDAP， 因 此 可 以 将 用 户 管理 交 给 OpenLDAP 3X Active 
Directory。 使 用 Active Directory 时 建议 安装 Active Directory plugin， 它 能 够 让 我 们 轻 轻 松 松 地 





进行 设置 。 
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NOTE 
我 们 可 以 在 下 列 URL 上 找到 关于 Jenkins 用 户 管 理 的 详细 介绍 ， 有 兴趣 的 读者 不 妨 参 考 
zd 


Standard Security Setup 
https://wiki.jenkins-ci.org/display/JENKINS/Standard«Security-«Setup 


Active Directory plugin 
https://wiki.jenkins-ci.org/display/JENKINS/Active«Directory-«plugin 


e 集群 

Jenkins 允许 以 主 从 方式 组 建 集 群 。 我 们 在 使 用 Jenkins 时 ， 往 往 一 建 就 是 十 几 二 十 个 定期 
执行 的 Job。 男 外 ，Job 的 执行 时 间 可 能 会 被 测试 拖 长 (测试 过 慢 )， 寻 致 1 台 计 算 机 无 法 处 理 所 
有 Job。 这 种 时 候 组 件 集 群 就 显得 行 之 有 至 了。 此 外 ， 对 于 需要 在 多 个 不 同 环境 中 进行 的 测试 而 
言 ， 集 群 也 是 一 种 很 好 的 解决 方法 。 

ARB, Jenkins 集群 的 机 制 如 下 所 述 。 





e 主 计算 机 回 从 计算 机 发 送 指令 
。 从 计算 机 执行 指令 
。 主 计算 机 统计 从 计算 机 的 结 


NOTE 
我 们 可 以 在 下 列 URL 上 找到 Jenkins 集群 的 详细 介绍 ， 有 兴趣 的 读者 不 妨 参 考 一 下 。 


Distributed builds 
https://wiki.jenkins-ci.org/display/JA/Distributed-«builds 


e CLI 
我 们 在 10.2.2 节 了 解 过 ， 除 了 Web UI ISh, Jenkins 还 有 其 他 CLI. Jenkins 的 CLI 很 适合 


用 来 执行 插件 定期 升级 等 标准 化 处 理 。 另 外 ，Jenkins 的 CLI 人 允许 远程 执行 ， 便 于 用 户 在 不 能 使 
用 Web 浏览 器 的 终端 上 操作 Jenkins。 
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NOTE 
我 们 可 以 在 下 列 URL 上 找到 Jenkins CLI 的 详细 介绍 ， 有 兴趣 的 读者 不 妨 参 考 一 下 。 


Jenkins CLI 
https://wiki.jenkins-ci.org/display/JA/Jenkins-«CLI 


10.8.2 ”进一步 改善 





到 10.7 市 为 止 ,我 们 学 习 了 如 何 用 Jenkins 签 出 源码 、 执 行 测 试 (测量 覆盖 率 )、 统计 
TODO 任务 、 发 送 结 采 通知 和 编写 文档 等 。 但 是 ， 这 些 内 容 只 是 整个 开发 流程 的 一 部 分 。 相 信 
各 位 还 希望 能 用 Jenkins 做 更 多 的 事 ， 比 如 下 面 这 些 。 





。 Pylint 等 的 静态 解析 

。 癌 正式 环境 或 演示 环境 部 署 
。 测试 已 部 署 的 产品 

e [5] PyPI 服务 名 上 传 

。 所 交付 产品 的 Zip 文件 存档 





另外 ， 只 要 Jenkins 的 运用 步 和 正轨， 我 们 将 会 在 改善 业务 流程 、 根 据 业 务 流程 和 目 定 义 
Jenkins 等 方面 产生 需求 。 
遇 到 此 类 需求 时 可 以 参考 下 述 信息 。 





NOTE 

官方 维基 上 自 科 的 信息 

: Jenkins Home: https: //wiki.jenkins-ci.org/display/JENKINS/Home 
邮件 列表 

: http://jenkins-ci.org/content/mailing-lists 

书籍 

- (Jenkins 入 门 与 实践 》 ( 技术 评论 社 ，2011 ) 

- Jenkins: The Definitive Guide ( O'Reilly Media, 2011 Ẹ ) 

《持续 集成 : 软件 质量 改进 和 风险 降低 之 道 》( 机 械 工业 出 版 社 ，2008 年 ) 





(D /&43 £7 [Jenkins RAP], 暂 无 中 文 版 。 
D 本 书 作 者 为 John Ferguson Smart, $6 A F 3 JA; 


译 者 注 
译 者 注 
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(Jenkins AT] » ( Shuwa System, 2012 年 ) 


虽然 用 Jenkins 能 完成 许多 精细 的 工作 ,但 这 不 代表 目 动 化 优 于 一 切 。 使 用 Jenkins KA H 
动 化 时 ,务必 要 你 证 作业 成 本 和 便捷 性 的 平衡 。 


10.9 小结 





本 章 对 持续 集成 进行 了 简单 的 说 明 ， 同 时 讲解 了 Jenkins 的 用 法 。 读 完 本 章 之 后 ， 相 信 各 位 
已 经 发 现 持续 集成 和 Jenkins 并 没有 想象 中 那么 难 。 虽 然 本 章 主 要 是 以 Django 为 例 进行 讲解 的 ， 
但 Jenkins 的 用 武之 地 远 不 止 于 此 。 各 位 可 以 从 小 规模 项 目 人 手 ， 了 逐步 感受 导入 Jenkins 的 方便 
bs 





OD 原 书 名 为 入门 Jenkins ]， 暂 无 中 文 版 。 译 者 注 





服务 公开 


第 3 部 分 主要 讨论 与 正式 环境 相关 的 一 些 较 现实 的 问题 。 这 部 分 将 介绍 向 正 
式 环境 公开 项 目 时 的 思路 和 流程 ， 研 究 在 正式 环境 中 改善 性 能 的 相关 问题 。 


第 11 章 ”环境 搭建 与 部 署 的 目 动 化 


G3 12x: D E 





第 11 章 ”环境 挫 建 与 部 署 的 目 动 化 


应 用 的 运行 离 不 开 执行 环境 。 

搭建 环境 要 做 的 事 非 常 多 ， 比 如 安装 依赖 包 、 设 置 中 间 件 、 设 置 应 用 本 身 等 。 这 些 工作 稍 
有 差错 就 会 导致 应 用 无 法 运行 ， 而 我 们 很 难 分 辨 问题 究竟 出 在 应 用 身上 还 是 环境 身上 ， 因 此 解 
决 问题 常常 要 费 一 番 力 气 。 

另外 ， 许 多 项 目的 环境 不 止 一 个 ， 除 正式 环境 外 还 需要 开发 环境 、 演 示 环 境 等 。 现 今 还 要 
考虑 到 向 外 扩展 ， 有 时 一 个 环境 甚至 是 由 几 十 台 服 务 器 共同 构成 的 。 要 手动 搭建 这 么 多 环境 还 
要 保证 不 出 错 ， 实 在 有 些 强 人 所 难 。 

为 保证 良好 的 服务 运营 ， 需 要 有 能 让 应 用 稳定 运行 且 便 于 维护 的 环境 。 本 章 将 就 搭建 稳定 
环境 的 方法 理论 以 及 通过 Ansible 实现 环境 搭建 、 部 署 自动 化 的 方法 进行 说 明 。 

本 章 的 目的 是 搭建 环境 的 自动 化 ， 但 是 如 果 过 于 随意 地 搭建 内 容 和 流程 ， 则 很 难 形 成 一 个 
稳定 的 环境 。 男 外 ， 在 这 种 状态 下 也 不 可 能 顺利 实现 自动 化 。 因 此 本 章 内 容 将 分 为 两 部 分 ， 第 
一 部 分 探讨 搭建 环境 的 流程 和 内 容 ， 第 二 部 分 讲解 如 何 将 第 一 部 分 的 内 容 自 动 化 。 





























11.1 确定 所 需 环 境 的 内 容 





首先 要 从 所 需 环境 的 内 容 人 手 。 环 境 一 旦 开始 使 用 就 很 难 再 进行 大 的 改动 ， 所 以 动手 搭建 
前 搞 清 所 需 环境 的 内 容 是 十 分 重要 的 。 

在 熟悉 搭建 环境 的 流程 之 前 ， 建 议 完 摸索 着 尝试 手动 搭建 。 等 到 熟悉 之 后 ， 再 考虑 结构 选 
择 和 搭建 过 程 日 动 化 的 问题 。 

利用 VirtualBox 和 快照 功能 可 以 带 助 我 们 快速 确定 所 需 环境 的 内 容 。 感 兴趣 的 读者 请 同时 
参考 附录 A。 

















11.1.1 网 络 结构 


许多 服务 是 由 多 台 服 务 融 组 合 实现 的 ， 所 以 在 探讨 服务 需 内 部 的 环境 搭建 之 前 ， 先 要 确定 
服务 器 的 组 成 结构 。 

可 用 服务 器 数 、 预 算 、 应 用 性 能 不 同 ， 所 需 的 服务 咒 结 构 也 是 千差万别 。 这 里 我 们 以 图 
11.1 所 示 的 结构 为 例 进 行 学 习 。 
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be 





I 


Su 
— AP2 
= 
gateway 


11.1 服务 器 结构 


e LB: HEFY (nginx ) 

e API, 2: HH s ( django/gunicorn ) 
° DB: 数据 库 (mysql ) 

e gateway: 跳板 服务 天 


@ Hl. S5 238 28 2H 

MERRI aec. SÉERHASSTBIBIRJ HR AE ate — 1 256—443. c 

这 里 我 们 将 分 担 各 个 职责 的 服务 硕 群 称 为 组 。 在 网 11.1 所 示 的 结构 中 ， 有 LB、AP、DB、 
gateway 这 4 个 组 。 

即便 某 个 职责 只 由 一 人 台 服 务 硕 完成 ， 我 们 也 认为 其 是 一 个 组 。 这 样 一 来 能 更 灵活 地 应 对 多 
Hit oS de t A] o 





NOTE 
按 职责 划分 的 服务 器 群 也 被 称 为 “角色 ”( Role )。 但 这 会 与 我 们 即将 讲 到 的 Ansible 的 
Role :&, MUERA "ZB" ( Group e 


€ EE SS as 

允许 从 外 部 网 络 耳 接 ssh Xo 1 Hi Ap ns zz ARÁR oA. TA Al 1S BHL IE PIRE 
通过 ssh iln e B or as o 

可 是 ， 一 旦 阻止 了 对 所 有 服务 硕 的 ssh， 我 们 便 无 法 通过 外 网 登录 ， 这 会 造成 很 多 不 便 。 所 
以 这 里 要 准备 一 台 用 作 登 录 跳 板 的 服务 大， 形成 通过 跳板 登录 各 服务 大 的 结构 。 
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11.1.2 服务 器 搭建 内 容 的 结构 化 
将 服务 器 搭建 内 容 按照 图 11.2 所 示 的 结构 进行 结构 化 。 









图 11.2 服务 器 搭建 内 容 的 结构 化 
这 个 结构 很 好 理解 。 在 中 间 件 里 定义 安装 和 设置 等 流程 ， 然 后 将 各 个 中 间 件 组 合 起 来 搭建 
服务 需 组 。 最 后 把 搭建 好 的 多 个 服务 需 组 整合 起 来 ， 就 形成 了 一 个 环境 。 
这 里 需要 特别 注意 的 是 ， 将 搭建 流程 整合 到 各 个 中 间 件 里 时 ， 如 果 只 简单 地 把 要 做 的 处 理 











按 顺 序 一 件 一 件 写 下 来 ， 很 容易 让 人 摘 不 请 究竟 哪个 步 又 属于 哪个 中 间 件 的 设置 。 加 强 对 这 个 
结构 的 理解 和 注意 ， 有 助 于 提高 目 动 化 的 效率 。 关 于 日 动 化 的 知识 我 们 将 在 11.2 TETY., 
根据 图 11.2 所 示 的 结构 ， 本 半 中 的 服务 胡可 划分 为 如 下 图 11.3 所 示 的 结构 。 


第 11 章 ， 环境 搭建 与 部 署 的 自动 化 | 273 


正式 环境 


load-balancers app-servers 


环境 设置 





图 11.3 ”本章 中 的 服务 器 的 搭建 内 容 
这 里 出 现 了 “环境 设置 "， 它 不 是 中 间 件 ， 而 是 我 们 为 了 便于 理解 ， 将 OS 的 设置 、 用 户 的 
创建 等 不 针对 特定 中 间 件 进行 的 操作 汇总 在 了 一 起 ， 并 统一 称 为 “环境 设置 ”。 
下 面 我 们 开始 学 习 具 体 的 搭建 流程 。 











11.1.3 ”用户 的 设置 


我 们 已 经 确定 好 了 服务 器 的 结构 ， 接 下 来 要 探讨 搭建 流程 。 首 先是 用 户 的 设置 。 

初始 状态 下 的 Ubuntu 以 ubuntu 用 户 为 登录 用 户 。 但 是 ， 如 末 让 黑 认 的 管理 员 用 户 来 做 维 
护 或 启动 应 用 ， 会 种 来 一 些 安 全 隐患 。 所 以 ,我 们 新 建 mainte 用 户 用 于 搭建 和 维护 ， 新 建 一 个 
不 能 直接 登录 的 普通 用 户 www 用 于 执行 应 用 。 














d useradd -m mainte 


d useradd -m www 


搭建 工作 会 经 常用 到 sudo， 因 此 要 给 mainte HARA sudo 权限 。 另 外 ， 考 虑 到 目 动 化 的 
问题 ， 最 好 让 mainte 不 需要 密码 就 可 以 执行 sudo。 

可 以 通过 编辑 /etc/sudoers 或 者 在 /etc/sudoers.d/ 中 添加 设置 文件 修改 sudo 权限 。 这 次 我 们 
用 后 一 种 方法 ， 创 建 /etc/sudoers.d/mainte。 
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$mainte ALL-(ALL) NOPASSWD:ALL 








smainte 表示 给 mainte 组 的 所 有 用 户 设置 sudo 权限 。 今 后 如 果 有 其 他 用 户 需 要 用 到 sudo, 
只 要 将 其 加 入 mainte 组 即 可 。 

至 于 www 用户， 要 让 它 只 保有 启动 应 用 所 需 的 最 小 权限 ， 因 此 不 设置 sudo 权限 。 

最 后 是 登录 设置 。mainte 用 户 今后 要 用 来 做 维护 工作 ， 所 以 需要 能 从 外 部 登录 。 

首先 用 ssh-keygen 生成 密 钥 文件 。 

















sudo su - mainte 


ssh-keygen -b 2048 


RUNE 


如 果 在 初始 设置 状态 下 执行 ssh-keygen， 会 在 /home/mainte/.ssh/ 下 生成 id rsa 和 id rsa. 
pub 两 个 文件 。 我 们 将 这 两 个 文件 下 载 到 本 地 PC 保管 。 
将 id rsa.pub 的 内 容 设置 到 authorized keys 中 ， 登 录 设 置 就 完成 了 。 


cat ~/.ssh/id rsa.pub >> -/.ssh/authorized keys 


Ur 


chmod 600 -/.ssh/authorized keys 


Ur 


经 过 上 面 的 设置 ， 我 们 在 mainte 用 户 的 “.ssh” 目 录 下 生成 了 密 钥 文件 ， 同 时 完成 了 对 应 
的 authorized key 的 设置 。 

这 样 设置 下 来 之 后 ， 就 能 很 轻松 地 在 多 个 服务 器 之 间 切 换 登 录 了 。 

最 后 查看 设置 是 否 正 确 。 











e mainte 用 户 能 用 下 载 到 本 地 PC 的 密 钥 文件 登录 服务 需 
e mainte 用 户 能 通过 sudo 切换 为 www 用 户 
e 器] 以 对 localhost 执行 ssh 


ssshnnleeanesre 


11.1.4 选 定 程序 包 
接 下 来 安装 应 用 运行 所 需 的 程序 包 。 
在 Ubuntu 上 运行 Python 应 用 时 ， 主 要 通过 apt-get 和 pip 安装 程序 包 。 
选择 要 安装 的 程序 包 时 请 注意 以 下 几 点 。 








中 安装 的 程序 包 要 尽量 少 
尽量 不 要 导 人 与 运行 应 用 无 关 的 程序 包 。 
育 目 寻 入 程序 包 会 使 我 们 无 法 准确 掌握 应 用 的 运行 条 件 ， 出 问题 时 很 难 分 辩 问 题 出 在 环 
境 上 还 是 应 用 本 号 上 。 
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要 导入 与 运行 应 用 没有 直接 关系 的 程序 包 时 ， 必 须 先 仔细 考虑 其 用 途 和 安装 范围 ， 再 确 
定 是 否 要 将 其 加 入 搭建 流程 。 
下 面 是 一 些 做 判断 的 例子 。 

e 应 用 的 日 录 结 构 很 复杂 ， 排 查 Bug 时 需要 tree 命令 的 辅助 

任何 环境 都 难免 需要 排查 Bug， 因 此 需要 将 tree 命令 加 入 构建 流程 。 

。 想 用 上 自己 常用 的 编辑 天 emacs 

基本 只 会 在 开发 环境 中 用 到 ， 所 以 仅 在 开发 环境 中 导入 。 

D 掌握 并 管理 程序 包 的 版 本 

对 开发 力度 较 大 的 应 用 / 库 而 言 ， 常 有 从 某 个 版 本 起 发 生 大 幅度 规格 变更 ,或 是 不 莱 容 
旧版 本 设置 文件 的 情况 发 生 。 
这 种 时 候 如 末 育 目 升级 了 版 本 ， 很 容 多 导致 应 用 无 法 运行 。 
要 防止 这 类 因 版 本 导致 的 事故 ， 重 点 在 于 把 握 安装 的 程序 包 的 版 本 以 及 确定 更 新 原则 。 
原则 主要 有 下 面 几 种 ， 各 位 可 以 为 每 个 程序 包 分 别 选择 合适 的 原则 。 

。 完全 国定 

不 考虑 版 本 升级 ， 仪 使 用 指定 版 本 的 程序 包 。 
。 国定 至 次 版 本 号 

固定 主 版 本 号 和 次 版 本 号 ， 人 允许 加 入 安全 更 新 和 Bug 修复 。 





























@ 通过 apt-get 安装 程序 包 

用 apt-get 或 yum 从 各 个 Linux 发 行 版 的 程序 包 版 本 库 安 装 程 序 包 时 ， 首 先 要 确认 各 个 发 行 
版 的 更 新 原则 。 

本 书 所 用 的 Ubuntu 原则 上 只 加 入 安全 更 新 和 Bug 修复 ， 不 进行 其 他 版 本 升级 。 

也 就 是 说 ， 环 境 本 号 就 处 于 上 述 “ 固 定 至 次 版 本 号 ”原则 的 状态 ,我们 不 必 多 作 修 改 。 程 
序 包 升 级 时 只 会 加 入 重大 的 Bug 修复 ， 不 会 更 新 主 版 本 号 和 次 版 本 号 。 

上 述 原 则 只 要 能 满足 我 们 的 需求 即 可 ， 没 有 什么 特别 需要 注意 的 地 方 。 现 在 我 们 可 以 通过 
简单 的 命令 安装 程序 包 ， 具 体 如 下 。 








$ sudo apt-get install packagename 
如 果 需 要 固定 版 本 ， 则 需要 在 程序 包 名 称 后 面 添加 等 号 以 及 版 本 号 。 具 体 如 下 所 示 。 


$ sudo apt-get install packagename-1.2.3-4ubuntu3 











包 名 和 版 本 号 都 可 以 用 正则 表达 式 。 比 如 ， 如 果 只 想 固定 到 次 版 本 号 ， 则 上 述 命令 可 以 写 
成 “1.2\..*” 的 形式 。 
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e 通过 pip 安装 程序 包 
用 pip 安装 程序 包 的 流程 在 第 9 间 中 有 详细 介绍 ， 不 清楚 的 读者 请 参考 该 部 分 。 
根据 11.1.4 节 得 出 的 结果 编写 requirements.txt， 修 正版 本 指定 ， 依 照 自身 情况 选择 是 否 分 


一 部 分 到 dev-requires.txt 和 tests-require.txt。 








完成 requirements.txt 之 后 ， 只 需 用 pip install -r requirements.txt 进行 安装 即 可 。 


图 封 财 环境 中 的 安装 

为 没有 网 络 连接 的 服务 需 搭 建 环境 时 ，aptrget 和 pip 这 种 通过 外 部 连接 安装 程序 包 的 方法 就 
不 好 用 了 。 另 外， 程序 包 提 供 方 Capt 版 本 库 、PyPI、GitHub 等 ) 故障 或 维护 时 也 是 同样 道理 。 

为 应 对 这 种 情况 ， 我 们 可 以 将 所 需 的 程序 包 事 先 保存 在 版 本 库 中 ， 然 后 进行 离线 安 狗 。 我 
们 把 这 些 打包 在 一 起 的 程序 包 叫 作 bundle。 

bundle 不 但 可 以 让 我 们 离线 安装 程序 包 ， 还 能 有 效 固定 版 本 以 及 削减 搭建 时 间 。 














O 通过 apt-get 安装 bundle 
apt-get 安装 的 程序 包 都 是 以 “.deb” 格 式 发 布 的 。 用 apt-get download 命令 可 以 获取 我 
们 需要 的 deb 程序 包 。 


$ mkdir aptcache && cd aptcache 

$ sudo apt-get download python3.4 
$ ls 

python3.4 3.4.0-2ubuntul amdq64 .deb 


deb 程序 包 用 dpkg -i 命令 安装 
$ sudo dpkg -i python3.4 3.4.0-2ubuntul amd64.deb 


但 是 有 一 个 问题 ，apt -get download 命令 只 能 获取 目标 程序 包 ， nds 
的 依赖 包 。 因 此 要 用 apt-cache depends fij 命令 dmn. 然后 在 通 述 方法 获取 它们 
的 deb 程序 包 。 





$ apt-cache depends Python3 .4 
python3.4 
Depends: python3.4-minimal 
Depends: libpython3.4-stdlib 
Depends: mime-support 
Suggests: python3.4-doc 
Suggests: binutils 


有 时 这 些 依赖 包 本 号 又 依赖 于 其 他 程序 包 ， 如 此 循环 下 去 不 知 何 时 是 个 头 ， 所 以 我 们 需要 
一 个 方法 来 一 次 性 获取 所 有 相关 的 程序 包 。 
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实际 上 , 用 apt-get install 命令 安装 程序 包 时 ， 目 标 程序 包 及 其 所 有 依赖 包 的 deb X 
件 全 都 会 被 下 载 到 缓存 目录 下 。 只 要 通过 -o 选项 临时 变更 缓存 目录 ， 就 能 将 目标 程序 包 和 其 所 
有 依赖 包 保存 到 任意 目录 下 了 。 





$ sudo apt-get install python3.4 -o Dir::Cache::Archives-/home/mainte/aptcache 


然而 有 一 点 需要 注意 ， 那 就 是 这 个 方法 无 法 获取 已 经 安装 的 程序 包 ， 因 此 需要 在 初始 状态 
的 环境 下 ( 比如 刚 用 VM 搭建 完毕 的 环境 ) 进行 操作 。 





O 通过 pip 安装 bundle 

旧版 本 的 pip 可 以 用 pip bundle 命令 进行 安装 ， 但 这 个 命令 在 pip 1.5 被 删除 。1.5 之 后 开始 
使 用 wheel, 9.1.4 节 详 细 介 绍 了 wheel 的 相关 内 容 ， 有 需要 的 读者 请 参考 该 部 分 。 

将 所 需 程 序 包 全 部 转换 为 wheel。 此 时 也 通过 requirements.txt 指定 程序 包 。 








$ pip wheel -r requirments.txt 





这 个 操作 会 在 当前 目录 的 wheelhouse 目录 下 生成 wheel。 我 们 将 整个 wheelhouse 目录 都 添 
加 到 应 用 的 版 本 库 中 。 
在 各 环境 下 都 可 以 通过 下 述 命令 从 wheelhouse 安装 程序 包 。 





$ pip install --no-index -f /path/to/my/repository/wheelhouse -r requirements.txt 


O bundle 的 维护 

更 新 或 水 加 新 的 程序 包 时 ， 需 要 将 程序 包 重 新 打包 成 bundle。 一 旦 漏 抒 这 个 步骤 ， 应 用 可 
能 出 现在 某 些 环境 下 能 运行 ， 在 某 些 环境 下 却 不 能 运行 的 情况 ， 问 题 很 难 排查 。 

重新 打包 bundle 是 一 件 非 党 党 琐 的 工作 ， 对 于 deb 程序 包 来 说 尤其 如 此 。 开 发 时 会 频繁 出 
现 程序 包 的 评 加 和 更 新 ， 因 此 过 早 地 bundle 化 会 惠 来 许多 肪 烦 。 毕 葛 开 发 环境 很 少 遇 到 无 法 连 
接 外 部 网 络 的 情况 ， 所 以 开发 中 建议 使 用 apt-get F pip install 来 安装 程序 包 。 等 到 正式 环境 就 
绪 再 考虑 bundle 4E AB, 438 , 

程序 包 管 理 进 入 bundle 阶段 后 ， 程 序 包 的 bundle 46th n] DASz 26 ERI EK E] 244. 














11.1.5 ”中 间 件 的 设置 


mysql, nginx 等 中 间 件 要 根据 使 用 环境 进行 设置 。 

我 们 往往 需要 在 大 量 服 务 胡 上 实施 或 更 新 中 间 件 的 设置 ， 如 打 这 些 全 神 手 动 去 完成 ， 很 容 
兄 出 现 蕊 镁 ， 导 致 发 生 问题 。 因 此 ， 实 现 中 间 件 设置 的 目 动 化 才 是 上 上 之 选 。 首 乞 摘 清 需要 上 月 
动 化 的 内 容 ， 选 出 对 象 文件 以 及 要 修改 的 项 目 。 本 章 用 作 例 子 的 服务 天 绪 构 中 包含 了 mysql, 
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nginx 和 gunicorn， 这 里 我 们 就 来 探讨 一 下 这 3 个 中 间 件 的 设置 。 


€ 让 中 间 件 设置 生效 的 方法 
目 动 化 更 新 中 间 件 的 设置 文件 需要 以 下 步 缀 。 











中 在 版 本 库 中 管理 对 象 文 件 
D 用 模板 语言 重新 描述 可 变 部 分 
D 将 模板 化 的 文件 翻译 过 来 直接 才 盖 原 设 置 文件 





步骤 CO 和 @) 提 到 的 模板 功能 是 Ansible 标 配 的 功能 ， 关 于 Ansible 的 知识 会 在 后 面 讲 到 。 探 
讨 设置 内 容 的 过 程 中 需要 我 们 手动 改写 设置 文件 ， 但 最 终 所 有 设置 都 要 通过 上 述 步 又 反映 出 来 。 
Ansible 采用 Jinja2 为 模板 编辑 郑 ， 因 此 本 下 的 模板 文件 都 是 以 Jinja2 格式 描述 的 。 

下 面 我 们 来 看 看 用 Jinja2 格式 摘 述 设置 文件 可 变 部 分 的 例子 。 











€ mysql 
MySQL 的 设置 描述 在 “/etc/mysqgl/conf.d/*” 中 。 本 例 的 设置 文件 为 /etc/mysql/conf.d/ 
myproject.cnf。 


讨论 所 需 项 目 并 编写 文件 。 
[mysqld] 


bind address - |ù MY LOCAL IP })} 
innoclo file per table = yeg 
innodb buffer pool size - [( MYSQL INNODB BUFFER POOL SIZE ]] 


在 mysql 的 设置 中 ， 有 些 值 会 根据 环境 变化 ， 比 如 根据 服务 套 IP 变化 的 bind_address， 根 
据 服 务 需 内 存 容 量变 更 最 优 值 的 innodb buffer pool size 等 。 如 果 事 先 将 这 些 值 设 置 为 变量 ，6 
以 在 中 间 件 变更 所 在 服务 融 时 轻松 完成 设置 更 新 。 














€) nginx 

nginx 的 设置 摘 述 在 /etc/nginx/conf.d/ap.conf 中 。 

nginx 的 conf.d 目录 下 设置 有 default.conf 和 example ssl.conf 两 个 文件 ， 它 们 是 用 来 显示 
nginx 默认 页 的 ， 与 我 们 要 搭建 环境 的 服务 顺 无 关 。 因 此 要 在 探讨 设置 之 前 把 这 两 个 文件 删除 。 








© LIST 11.1 /etc/nginx/conf.d/ap.conf 


upstream app { 
(* for server in NGINX UPSTREAMS %} 
server {{ server ]):8000; 


{1% endfor z} 
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server { 
listen {% if SSL %}443{% else %}80{% endif %}; 
server name {{ DOMAIN }}; 


iod Sn 

Sie 

ssl certificate [[ SSL.CERTIFICATE Y}, 
ssl certificate key (( SSL.KEY ]); 

($ endif $) 


需要 在 upstream 指令 中 指定 多 个 反问 代理 对 象 的 服务 如 地 址 。 这 里 我 们 是 用 变量 NGINX 
UPSTREAMS 来 存储 服务 硕 地 址 清单 ， 并 通过 for 语句 来 指定 服务 天 地 址 的 。 

另外 ， 我 们 还 对 server 指令 内 是 否 存在 SSL 的 设置 进行 了 判断 ， 并 根据 情况 进行 了 listen 
端口 的 切换 以 及 ssl certificate 的 设置 。 出 于 预算 原因 ， 我 们 的 项 目 并 不 是 每 个 环境 都 使 用 SSL, 
所 以 在 这 里 保证 了 两 种 设 定之 间 的 简单 切换 。 

可 见 ， 利 用 Jinja2 模板 的 让 和 for 能 做 出 复杂 的 情况 分 类 ( LIST 11.1 )。 但 有 一 点 需要 注意 ， 
过 度 使 用 控制 语句 会 降低 程序 的 可 读 性 ， 增 加 修改 的 难度 。 

















@ gunicorn 
让 gunicorn 通过 upstart 启动 。 创 建 /ect/init/myapp.conf 文件 用 作 启 动 脚本 ， 脚 本 内 容 如 下 。 


upstart 的 文档 
http://upstart.ubuntu.com/ 


description "myapp" 





start on (filesystem) 


stop on runlevel [016] 


respawn 
console log 
Setuid www 
Setgid www 
chdir (| SOURCE DIR < 


gunicorn myapp.wsgi:application --bind={{ MY LOCAL IP }}:8000 --workers={{ 


exec DJANGO SETTINGS MODULE={{ DJANGO SETTINGS }} {{ SOURCE DIR }}.venv/bin/ 
GUNICORN WORKERS j] | 
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上 述 例子 将 许多 值 蔡 换 为 了 变量 。 等 到 月 动 化 的 时 候 ， 这 些 地 方 就 会 发 挥 出 其 效 末 了 。 


SOURCE DIR 

放置 源码 目录 。 虽 然 这 个 值 很 少 因 为 环境 而 变 ， 但 换 成 变量 能 防止 键入 错误 。 

DJANGO SETTINGS 

Django 的 settings 文 件 需 要 根据 环境 而 变 。 将 它 设置 为 变量 之 后 ， 我 们 就 可 以 在 所 有 环境 
中 应 用 同一 个 模板 了 。 

MY LOCAL IP 

目 身 服务 融 的 本 地 耻 。 百 接 拿 mysql 设置 文件 中 定义 的 变量 来 用 。 

GUNICORN WORKERS 














gunicorn 的 worker 进 程 数 。 





将 中 间 件 的 设置 文件 模板 化 时 ， 需 要 考虑 以 下 儿 个 问题 。 








e 哪个 设置 值 需要 用 变量 特 换 

因 环境 而 变 的 值 ， 以 及 容易 输入 错 的 值 〈 比如 较 长 的 文件 路 径 ) 。 
e 有 多 个 中 间 件 共用 的 变量 吗 

所 有 环境 共享 的 值 要 设计 成 共用 一 个 变量 。 














11.1.6 部署 


部 车 就 是 将 应 用 安置 到 环境 中 ， 使 其 进入 可 运行 状态 。 
应 用 源码 的 安置 、 中 间 件 说 置 的 反映 、 中 间 件 的 重 局 等 都 属于 部 署 工作 。 
本 市 将 对 上 述 3 个 工作 进行 说 明 。 








e 源码 的 安置 与 更 新 

源码 的 安置 用 Mercurial 的 clone 和 pull 即 可 轻松 完成 。 利 用 标签 和 分 文 的 功能 ， 还 能 灵活 
应 对 回 深 等 操作 。 

如 果 有 从 各 环境 均 可 连接 的 公共 密 钥 认证 的 中 央 版 本 库 ， 那 么 最 好 从 该 版 本 库 进 行 clone $$ 
作 。 这 里 我 们 假设 中 央 版 本 库 放 在 myrepository.com。 

clone 时 用 11.1.3 市 创建 的 www 用户 。 访 问 版 本 库 时 用 到 的 公共 密 铀 和 私有 密 钥 要 事先 设 
置 好 。 

本 例 中 ， 我 们 把 版 本 库 设 置 在 /var/www/myproject. 








$ cd /var/www/ 
$ hg clone ssh://myrepository.com/myproject 
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执行 clone 操作 之 后 就 完成 了 应 用 源码 的 安置 工作 。 更 新 工作 只 需要 在 各 个 服务 器 上 对 版 本 
库 进 行 pull/update 即 可 。 


$ cd /var/www/myproject 
$ hg pull; hg update default 


根据 用 途 和 环境 不 同 可 以 将 update f EUER HIA Sed EA. EA CRISE FER e 
实现 目 动 化 时 上 只 需 将 其 改 为 变量 ， 让 其 能 够 被 蔡 换 即 可 。 














没有 可 通过 公共 密 钥 认证 的 中 央 版 本 库 时 该 怎么 办 

源码 在 Mercurial 上 管理 时 ， 只 要 我 们 能 使 用 clone 操作 ， 就 能 将 源码 部 署 到 环境 中 。 但 是 
WR lk 2 ee Se ee RN VE 384A 8X clone Sn NT RIT B3MES 

这 种 时 候 可 以 先 将 主 版 本 库 clone 到 gateway 服务 器 上 ， 然 后 各 环境 服务 器 再 从 gateway 
服务 器 上 的 版 本 库 进行 clone， 这 样 就 能 将 输入 密码 的 次 数 降 到 最 少 ( 图 11.4 )。 


版 本 库 服务 器 


Q@gateway 从 版 本 库 服务 器 进行 clone/pull 操 作 


clone/pull 
( 此 时 为 密码 认证 ) 
gateway 其 他 服务 器 

m clone/pull 

@ 其 他 服务 器 经 由 ssh 从 gateway 进 行 

clone/pull 操 作 

图 11.4 ”密码 认证 环境 中 的 源码 部 署 
€ 中 间 件 设置 的 反映 


如 11.1.5 节 所 述 ， 现 阶段 需要 手动 改写 模板 部 分 并 上 传 至 各 环境 ， 从 而 反映 设置 。 
改写 过 程 中 要 时 刻 注意 设置 文件 有 没有 放 错 地 方 ， 有 没有 不 小 心 改写 了 未 加 入 管理 的 文件 。 














@ 重启 中 间 件 
守护 进程 的 启动 和 停止 要 使 用 service 命令 。 
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$ sudo service myapp restart 


11.2 用 Ansible 实现 自动 化 作业 





上 面 我 们 大 致 总 结 了 搭建 环境 的 流程 ， 现 在 来 看 看 如 何 用 Ansible 实现 日 动 化 搭建 环境 。 


11.2.4 Ansible 简介 


Ansible 是 基于 Python 研发 的 结构 管理 工具 。 不 过 它 除了 能 进行 结构 管理 之 外 ， 还 能 将 许 
多 针对 服务 需 的 操作 自动 化 。 
Ansible 本 号 由 Python 实现 ， 但 运行 所 需 的 设置 文件 均 以 INI 格式 或 YAML 格式 描述 ， 因 
此 没有 Python 知识 也 能 使 用 它 。 
另外 ，Ansible 不 像 Chef 和 Puppet， 它 不 需要 在 被 操作 的 服务 器 上 安装 代理 程序 。 只 要 服 
ZAI ssh 登录 ，Ansible 就 能 执行 相关 操作 。 
Ansible 的 主要 概念 有 以 下 5 个， 我 们 随后 将 依次 进行 了 解 。 





e inventory 
e module 
e role 

e playbook 


9 vars 


NOTE 
本 书 只 介绍 了 Ansible 的 一 部 分 功能 ， 想 了 解 其 基本 使 用 方法 以 及 其 他 功能 的 读者 可 以 参考 
Ansible 的 官方 文档 。 


FEEP /doce ansible. com/ 


® inventory 


inventory 是 保存 有 执行 对 象 C 即 主机 ) 清单 的 INI 格式 的 设置 文件 。 主 机 通过 IP 地址 或 主 
机 名 指定 。 





T9 Gg 二 
192 168-022 
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EO o5 0E 
T920 5168 0 4 
T92 Gm0 5 


Ansible 只 能 访问 这 里 指定 的 主机 ， 因 此 我 们 需要 为 不 同 的 执行 环境 准备 不 同 的 inventory 
文件 。 
另外 ， 主 机 可 以 用 段 进 行 分 组 。 后 面 讲 到 的 playbook 和 vars 会 用 到 这 里 定义 的 组 。 


[load-balancers] 


TOPPS SMOR? 


[app-servers] 
192.168.0.3 
192.168.0.4 


[db-servers] 


192 6859-5 


同一 个 主机 可 以 同时 出 现在 多 个 组 里 。 比 如 在 所 有 功能 全 由 一 台 主 机 实现 的 开发 环境 中 ， 
inventory 就 是 下 面 这 个 样子 。 


[load-balancers] 


L92- 168-06 


[app-servers] 


L2 T6 20/6 


[db-servers] 


.92,168.,0.6 





Inventory - Ansible Documentation 





http://docs.ansible.com/intro inventory.html 





Dynamic Inventory 


inventory 文件 除了 可 以 指定 INI 格式 的 文件 外 ， 还 可 以 指定 可 执行 的 脚本 文件 。 我 们 将 这 
类 文件 称 为 Dynamic Inventory， 适 用 于 Amazon EC2、Google Compute Engine, Docker 等 需 
要 频繁 变更 对 象 主机 信息 的 情况 。 

Ansible 的 版 本 库 中 有 以 上 述 EC2 等 为 对 象 的 示例 Dynamic Inventory， 各 位 不 妨 加 以 
参考 。 
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Ansible plugins/inventory 
https://github.com/ansible/ansible/tree/devel/contrib/inventory 


Dynamic Inventory 


http://docs.ansible.com/intro dynamic inventory.html 


€ module 
Ansible 以 module 为 单位 定义 对 服务 融 的 操作 。 
Ansible 本 身 目 带 了 许多 module， 可 以 将 它们 组 合 起 来 ， 实 现 多 种 操作 。 


Module Index - Ansible Documentation 
http://docs.ansible.com/modules by category.html 


IH SE SEUÉ8— x JUI, module 可 用 任何 语言 来 实现 。 当 标准 模块 无 法 满足 需求 时 ， 可 以 直 
接 将 现 有 脚本 封装 成 module 来 使 用 。 


Developing Modules - Ansible Documentation 
http://docs.ansible.com/developing modules.html 


TA T module 时 以 task 形式 描述 目 身 的 传 值 参 数 及 其 他 参数 。 




















- name: install nginx 
sudo: yes 
apt: name=nginx 
- name: install mysql 
sudo: yes 
api 
name: mysqgl-server 
State: latest 


updgscEcacHe ve 


module 的 传 值 参数 以 key-value 的 形式 描述 ， 各 传 值 参 数 之 间 用 空格 区 分 。 或 者 也 可 以 用 
字典 形式 描述 。 传 值 参数 较 多 时 建议 使 用 字典 形式 。 
@ role 


role 可 以 批量 重复 利用 task。 
role 的 结构 如 LIST 11.2 所 示 。 





& LIST 11.2 role 的 目录 结构 


roles/ 


--- nginx/ 
+-- tasks/ 
== Yd 


+-- handlers/ 


+-- main.yml 
+-- vars/ 
+-- main.yml 


+-- defaults/ 


+-- main.yml 
+-- files/ 
+-- nginx.repo 


+-- templates/ 
+-- conf.d/ 
t->- AD, CANE 
+-- meta/ 


+-- main.yml 


e tasks 


task 定 义 。 定 义 描 述 在 该 目录 的 main.yml 中 。 


e handlers 
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handler 的 定义 。 由 task 定 义 的 notify 指 定 并 调用 。 同 上 ， 在 main.yml 中 描述 。 


9 vars 





该 role 使 用 的 变量 。 同 上 ， 在 main.yml 中 描述 。 


e defaults 


上 述 变量 的 默认 值 。 同 上 ， 在 main.yml 中 描述 。 


e files 





该 role 的 task 中 ， 文 件 关 联 模块 用 到 的 文件 。 


e templates 


该 role 的 task 中 ，template 模 块 用 到 的 Jinja2 模 板 文 件 。 


e meta 


元 信息 。 可 定义 role 之 间 的 依赖 关系 等 。 


role 的 共享 
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role 也 能 像 PyPI 一 样 在 Web 上 公开 及 共享 。Ansible Galaxy. 是 Ansible 公司 运营 的 网 站 ， 


任何 人 都 可 以 在 这 里 免费 上 传 和 下 载 role。 


(D https://galaxy.ansible.com/ 
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从 Ansible Galaxy 上 下 载 role 时 ， 需 要 用 ansible-galaxy install 命令 。 这 个 命令 只 需 安装 
Ansible 就 可 以 使 用 了 。 下 载 的 role 默认 安装 到 /etc/ansible/roles 目录 下 ， 我 们 可 以 通过 -p 选 
项 指定 安装 位 置 。 

$ ansible-galaxy install username.rolename -p ROLES PATH 


使 用 ansible-galaxy init 命令 可 以 生成 包含 meta/main.yml 和 tasks 目录 等 内 容 的 样板 文件 。 
这 个 命令 原本 是 为 方便 用 户 向 Ansible Galaxy 上 传 role 而 设计 的 ， 但 对 于 不 想 公 开 的 role 同样 
好 用 。 因 此 各 位 在 制作 role 的 时 候 不 妨 试 试 这 个 命令 。 


$ ansible-galaxy init rolename 


€ playbook 
playbook 是 YAML 格式 的 文件 ， 用 来 定义 要 执行 的 处 理 。 


- hosts: load-balancers 
sudo user: mainte 
roles: 
- django 

在 hosts AJE 4E ZA as. iX TRAE inventory 中 定义 的 群 和 名， 可 以 对 该 群 中 的 主机 执行 
task。 指 定 为 al 则 以 所 有 主机 为 对 象 。 

定义 sudo: yes 之 后 ， 该 playbook 将 全 部 由 sudo 用 户 执行 。sudo 用 户 默 认为 root。 想 使 用 
root 以 外 的 用 户 时 需要 在 sudo. user 处 指定 。 

roles ARDI YAML 的 列表 形式 指定 要 执行 的 role。 虽 然 可 以 在 tasks 处 直接 描述 task， 但 除 
了 没有 现成 脚本 的 情况 以 外 ， 还 是 建议 使 用 role; 


Playbooks - Ansible Documentation 
http://docs.ansible.com/playbooks.html 
@ vars 


playbook, task, role 的 模板 中 都 可 以 使 用 变量 。vars 的 设置 方法 有 很 多 种 ， 这 里 只 介绍 比 
较 有 代表 性 的 。 








O role 的 defaults 
定义 该 role 使 用 的 变量 的 默认 值 。 这 里 设置 的 值 一 般 都 是 无 法 直接 运行 的 临时 值 或 空 值 ， 
实际 的 值 在 group vars 中 描述 ， 等 到 运行 时 再 进行 覆 新 。 这 样 一 来 只 需 看 defaults 就 能 掌握 role 
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所 需 的 全 部 变量 ， 使 role 的 重复 利用 成 为 可 能 。 
O group. vars 

针对 inventory 中 定义 的 组 进行 设置 。Ansible 会 谈 取 group. vars 目录 下 的 YAML 格式 文件 。 
文件 名 对 应 组 名 。 另 外 ,文件 名 为 al， 会 对 所 有 组 套用 变量 。 

















O host vars 
针对 inventory 中 定义 的 主机 进行 设置 。Ansible SEH host. vars 目录 下 的 YAML 格式 文 
件 。 文 件 名 对 应 组 名 。 





11.2.2 文件 结构 
与 Ansible 关联 的 文件 全 者 要 在 一 个 目录 下 统一 管理 。 本 章 示 例 的 目录 结构 如 LIST 11.3 所 示 。 


&3 LIST 11.3 ansible 脚本 群 的 文件 结构 


+-- deployment/ 
+-- group vars/ 


+-- all 


+-- host vars/ 


+-- roles/ 
--- environ 
+-- nginx 
+-- mysql 
+-- inventory/ 
+-- production 
+ dev 
+ site. yml 
+ ap.yml 
十 Lo. yml 





这 些 文 件 也 都 要 放 在 版 本 库 中 进行 管理 。 管 理 方法 可 以 有 以 下 2 种 。 





e 创建 专用 的 版 本 库 进 行 管理 
e 杞 应 用 的 源码 放 在 同一 个 版 本 库 中 进行 管理 


e 在 专用 的 版 本 库 中 管理 
如 果 没 必要 或 者 不 希望 应 用 的 开发 与 环境 搭建 同步 ， 可 以 把 源码 与 Ansible 的 文件 群 放 在 不 
同 版 本 库 中 进行 管理 
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Ansible 关联 文件 的 数量 通 当 很 大 ， 如 果 不 想 让 源码 的 版 本 库 太 复兴， 同样 可 以 用 这 个 方法 。 


© 与 应 用 的 源码 放 在 同一 个 版 本 库 中 进行 管理 

在 应 用 的 版 本 库 中 专门 创建 一 个 用 于 管理 这 些 文件 的 目录 。 这 样 做 的 好 处 是 能 在 开发 过 程 
中 让 应 用 开发 与 环境 搭建 内 容 的 变更 对 应 起 来 。 

我 们 大 部 分 项 目 都 采用 了 这 种 方法 。 没 有 特殊 要 求 的 情况 下 文件 路 径 以 myproject/ 
deployment/ 为 基准 。 











11.2.8 执行 Ansible 


创建 好 的 脚本 用 ansible-playbook 命令 执行 。 对 象 环境 的 选择 是 通过 切换 inventory 来 
实现 的 ， 因 此 要 用 -i 选项 明确 指定 inventory. 





$ ansible-playbook -i inventory/production.ini site.yml 
在 本 革 的 结构 中 ， 会 频繁 用 到 指定 了 tag 的 执行 操作 。- 选项 可 以 在 执行 时 指定 任意 标签 。 


$ ansible-playbook -i inventory/production -t deploy site.yml 


11.2.4 与 最 初 确定 的 结构 相对 应 
11.1 方 确定 的 搭建 内 容 可 以 与 Ansible 的 各 概念 对 应 起 来 。 图 11.5 与 图 11.2 相对 应 。 








inventory+vars 


playbook 


ask NW 
module + 传 值 参数 | 





playbook | 


11.5 Ansible 的 概念 与 服务 器 搭建 内 容 的 对 应 
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e 环境 = inventory + vars 

针对 各 个 环境 (正式 环境 、 开 发 环境 、 过 渡 环 境 等 ) 编写 inventory 文 件 。 男 外 ，Ansible 
会 日 动 谈 取 与 inventory 的 描述 内 容 相 对 应 的 vars。 

服务 需 组 = inventory 的 段 

前 面 定 义 的 服务 磊 组 在 inventory 中 是 以 段 形式 定义 的 ， 各 上 段 中 列举 了 主机 。 

各 服务 天 组 的 搭建 流程 = playbook 

给 各 个 组 分 别 创建 lb.yml、ap.yml、db.yml、gateway.yml 文 件 ， 将 组 设置 成 hosts。 另 外 ， 
创建 一 个 include 所 有 playbook 的 playbook， 方便 一 次 性 搭建 所 有 环境 。 这 个 playbook 一 般 
命名 为 site.yml。 

针对 各 个 中 间 件 的 搭建 流程 = role 

以 中 间 件 为 单位 创建 rnle， 各 服务 器 组 用 对 应 其 所 需 role 的 playbook 统 一 管理 。 

其 他 环境 设置 role 

不 依赖 于 特定 中 间 件 的 环境 设置 〈 创 建 用 户 等 ) 也 以 role 形 式 描述 。 























11.2.5 ”将 各 步骤 Ansible 化 


€ playbook/role 的 设计 
着 手 细节 步骤 之 前 ， 要 先 探 讨 搭建 流程 的 各 个 步骤 应 该 整合 到 怎样 的 role/playbook 之 中 。 
我 们 对 前 面 学 习 的 搭建 操作 流程 进行 如 下 分 类 ， 然 后 分 割 到 各 个 role 中 。 








J 应 该 套用 到 所 有 服务 器 中 的 操作 
除了 本 章 讲 到 的 创建 用 户 之 外 ， 比 较 常 见 的 还 有 ntp 和 时 区 设置 。 
我 们 将 这 些 处 理 整 合 到 名 为 environ 的 role 中 ， 对 所 有 服务 如 组 进行 僚 用 。 
D 特定 服务 需 组 使 用 的 中 间 件 的 设置 
为 每 个 中 间 件 编写 一 个 role， 以 达到 分 割 的 目的 。 
O 部署 
包含 到 对 象 中 间 件 的 role 里。 设置 tag 以 保证 能 单独 执行 部 署 操 作 。 然 后 将 分 割 好 的 
role 组 合成 playbook。 以 下 是 正式 环境 的 例子 。 























- hosts: app-servers 
roles: 
- environ 
= jexae! sion 
- repository 


- django 


290 | 第 3 部 分 服务 公开 
- appserver 


- hosts: db-servers 
roles: 
- environ 


- mysql 


- hosts: load-balancers 
roles: 
- environ 


- nginx 





AU BEY Fé Je Sn] AA ARK 73 NE, MAAE Y. 


e 用 户 设 置 
用 户 的 创建 和 设置 可 以 用 user 模块 完成 。 


TASKS 
- user: name=mainte 


- user: name-www 


fti B) file EE E [n] sudoers.d 目录 下 放置 文件 。 本 例 的 文件 内 容 比 较 简 单 ， 因 此 可 以 通过 
content 传 值 参 数 直 接 描述 脚本 内 容 来 进行 设置 。 


tasks: 
- file: 
dest: /etc/sudoers.d/mainte 


content: "£Zmainte ALL-(ALL) NOPASSWD:ALL" 





公开 密 钥 的 设置 用 authorized keys 模块 。 传 值 参数 处 需要 些 公 开 密 钥 的 字符 串 ， 由 于 字符 
PRK, ， 我 们 用 group_vars/all 文件 的 变量 代替 。 


mainte pubkey: AAAA1234512345... 


tasks: 
- Author zec) keys: 
user: mainte 


key: "{{mainte_pubkey}}" 





密 钥 文 件 在 版 本 库 中 管理 ， 通 过 file 模块 放置 。 这 里 不 要 忘记 修改 权限 。 


tasks: 
- file: 


sre: mainte geckey 
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dest: /home/mainte/.ssh/id rsa 


mode: 0600 








本 例 的 src 只 指定 了 文件 名 ， 它 在 这 里 其 实 是 相对 路 径 ， 该 相对 路 径 是 基于 下 面 两 个 中 的 


LAN 


lo 





e playbook 的 目录 
e 包含 该 task HJ role 的 files 目录 


@ deb 程序 包 的 安装 
安装 deb 程序 包 时 使 用 apt 模块 。 指 定 版 本 的 方式 与 apt-get 相同 。 





= APLs 
name: mysql-server-5.5=5.5.40-0ubuntu0.14.04.1 





用 with items H LUTZ BUY BU RER MEAE E— T task 中 。 


= sue 
name: "{{ item }}" 
with items: 
- mysql-server-5.5=5.5.40-0ubuntu0.14.04.1 


- Nginx 


@ 通过 pip 安装 程序 包 
Ansible 有 兼容 pip 的 pip 模块 ， 使 用 前 需要 先 安 装 pip。 


- name: install pip 
shell: curl -L https://bootstrap.pypa.io/get-pip.py | python creates-/usr/ d 
local/bin/pip 


使 用 shell 模块 时 ， 如 采 传 值 参数 creates 处 指定 的 文件 已 经 存在 ， 该 步骤 将 被 强制 跳 过 。 本 
例 是 通过 检查 是 否 存 在 /user/local/bin/pip 来 判断 是 否 需 要 执行 该 步骤 的 。 

由 于 这 些 模 块 都 可 以 目 由 执行 命令 ， 因 此 用 等 性 需要 我 们 目 己 来 验证 。 只 要 给 传人 参数 
creates 指定 了 文件 ， 当 被 指定 的 文件 存在 时 ， 当 前 步骤 就 会 被 强制 跳 过 。 本 例 是 通过 检查 /user/ 
local/bin/pip 是 否 存 在 来 判断 是 否 需要 执行 该 步骤。 

安 闻 完成 后 pip 模块 就 能 用 了 。 

















- name install packages 
pip: name-[(item]] 
with items: 


- virtualenv 
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我 们 在 第 1 章 中 也 了 解 到 ， 应 用 所 需 的 程序 包 要 安装 在 virtualenv 环境 中 。 因 此 我 们 把 搭建 
virtualenv 环境 的 步骤 也 写 了 进来 。 


- name: create virtualenv 
sudo user: www 


command: virtualenv venv chdir-/var/www/ creates-venv/bin/activate 


- name: install 
sudo user: www 


pip: requirements-/var/www/myproject/requirements.txt virtualenv-/var/www/venv 


pip 模块 会 问 virtualenv 参数 处 指定 的 环境 安装 程序 包 ， 所 以 我 们 在 这 里 指定 虚拟 环境 的 路 
径 。 另 外 ， 只 把 name 参数 蔡 换 为 requirements 参数 并 指定 requirements.txt 的 路 径 ， 就 可 以 使 用 


requirements.txt 了 。 


@® 中 间 件 设置 的 反映 

放置 、 更 新 设置 文件 要 用 template 模块 。 

之 前 我 们 在 设置 文件 中 使 用 了 一 些 尚未 定义 的 变量 ,现在 在 group vars 和 role 的 defaults/ 
main.yml 中 定义 它们 。 比 如 对 nginx.conf 中 使 用 的 变量 要 作 如 下 定义 ( LIST 11.4 )。 

















© LIST 11.4 group_vars/all 


DOMAIN: myproject.example.com 
NGINX UPSTREAMS: 

= 192- 168.053 

= 192.168.0.4 


eo Lis 
OERTEIPBICATE: mvprojectcocrt 
KEY: myproject.key 





变量 准备 完毕 后 开始 写 放 置 配置 文件 的 task。 涉 及 多 个 文件 时 推荐 使 用 with items. 


tasks: 
- template: 
sro M em 
dest: /etc/nginx/"[[ item |)" 
witha Ee. 


conde //dgumicosmoconf 








template 模块 的 文件 路 径 引 用 的 是 包含 该 task 的 role 的 templates 目录 。 保 持 templates 目录 
的 相对 路 径 与 文件 放置 目标 目录 的 相对 路 径 一 致 能 够 简化 描述 。 
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e 部 署 

Abr HJ task 也 写 在 各 个 role 的 tasks 中 。 摘 述 时 要 给 该 task 设置 tag。 设 置 tag 能 让 我 们 单 
独 拿 出 与 部 署 相 关 的 task 来 执行 。 

按照 本 章 的 结构 ， 我 们 定义 下 述 tag。 


e configure 
设置 文件 的 更 新 
e Update 
源码 的 更 新 
reload 
重新 加 载 中 间 件 设置 
deploy 





JAfTupdate, configure, reload 


e 设置 的 更 新 
给 在 “中 间 件 设置 的 反映 ”部 分 编写 的 template 模块 的 task 添加 configure 和 deploy 标签 。 








template: 

Ecc m Eee 

dest: /etc/nginx/"([ item }}" 
with items: 

- Gonar, d/gunicorn Cont 
tags: 

- configure 


- deploy 


© 中 间 件 的 重启 
经 由 sysvinit 或 upstart 启动 的 中 间 件 可 以 用 service 模块 重启 或 重新 加 载 。 








- Service: 
name: nginx 
state: reloaded 
tags: 
- reload 


- deploy 


如 末 使 其 与 Ansible 的 Notify 机 制 相 结 合 ， 则 可 以 规定 仪 在 设置 文件 被 修改 时 自动 重新 加 
载 中 间 件 。 
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通过 Notify 调用 的 task Æ role 的 handlers/main.yml 中 描述 。name SWINE, MUZ 
指定 一 个 在 整个 项 目 中 独一无二 的 名 字 。 





© LIST 11.5 roles/nginx/handlers/main.yml 


- name: reload nginx 
Service: 
name: nginx 


State: reloaded 





接 下 来 在 调用 方 的 notify 参数 处 指定 通过 LIST 11.5 设置 的 name。 这 个 task 的 返回 值 changed 
为 True 时 (对 template 模块 而 言 是 文件 内 容 被 更 新 时 ) 将 执行 notify 指定 的 task( LIST 11.6 )。 





© LIST 11.6 roles/nginx/tasks/main.yml 


- name: configure nginx 
template: 
hac t | ern) d 
dest: /etc/nginx/"(( item j]" 
wLa itens: 
> Coni, E/gunicorn , coni 
tags: 
- configure 
- deploy 
notifye 


- reload nginx 








使 用 Notify 可 以 让 我 们 不 必 分 神 去 注意 重新 加 载 设 置 的 问题 ， 但 会 使 单独 执行 重新 加 载 或 
重启 ， 以 及 只 修改 设置 不 重启 等 类 似 操作 变 得 难以 实现 。 因 此 需要 根据 项 目的 实际 情况 选择 合 
适 的 方法 。 





e i5 iiid 
通过 Mercurial 放置 源码 的 操作 可 以 用 hg 模块 来 完成 ， 但 需要 事前 完成 安 闻 Mercurial, &! 
建 目 录 、 设 置 权限 等 准备 工作 。 
把 这 一 系列 工作 整合 到 名 为 repository 的 role 中， 让 需要 放置 源码 的 服务 融 组 能 够 使 用 该 role。 














Eu 


name: mercurial 


- file: 
State: directory 


dest: /var/www/ 
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Owner: WWW 


mode: 755 


= 和 98 
repo: ssh://user@myrepository.com/myproject 
dest: /var/www/myproject 
Eva 
tags: 
- update 
- deploy 


为 了 能 够 更 新 成 任意 版 本 而 不 仪 限 于 default, ix Hf hg 模块 的 传 值 参数 revision 设 为 变量 。 
根据 需要 还 可 以 将 放置 源码 的 目标 项 目 名 、 版 本 库 URL 也 设 为 变量 ， 方 便 蔡 换 和 引用 ， 从 
而 灵活 应 对 多 种 需求 。 

















11.2.6 ”整理 Ansible 的 执行 环境 


本 例 中 的 环境 如 11.1.1 WR, BR gateway 服务 帝 以 外 全 都 无 法 从 外 部 进行 ssh， 因 此 我 们 
无 法 从 本 地 环境 操作 所 有 服务 器 。 男 外 ， 如 果 给 所 有 相关 人 员 的 本 地 环境 中 都 搭建 Ansible 的 执 
行 环境 ， 那 么 每 次 调换 或 新 增 负 责 人 时 都 要 搭建 一 次 环境 。 

这 种 时 候 ， 最 好 的 解决 办 法 就 是 在 一 个 项 目 全 体 成 员 共 享 的 、 可 连接 环境 中 所 有 服务 需 并 
且 与 应 用 运行 没有 直接 关系 的 gateway 服务 船上 搭建 Ansible 的 执行 环境 。 

虽然 我 们 也 和 希望 通过 Ansible 完成 gateway 服务 需 的 整理 ， 但 这 又 涉及 到 用 Ansible 整理 
Ansible 执行 环境 的 目 举 问题 。 

这 里 我 们 从 手头 环境 执行 Ansilbe， 以 解决 这 一 问题 。 但 有 一 点 要 注意 ， 执 行 这 部 分 操作 时 
gateway 服务 器 上 还 不 存在 mainte 用 户 。 虽 然 我 们 设想 用 mainte 进行 维护 工作 ， 但 构建 环境 时 
无 法 使 用 该 用 户 。 所 以 要 为 root 或 ubuntu 用 户 创 建 一 份 临时 的 inventory 文件 (LIST 
11.7 ~ LIST 11.9 )。 




















EJ LIST 11.7 gateway 搭建 时 所 需 的 ini 


[gateway] 


gateway .example.com ansible ssh user=ubuntu 


© LIST 11.8 gateway.yml 


- hosts: gateway 
sudo: yes 
roles: 


- environ 
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tl 


- ansible 


© LIST 11.9 roles/ansible/tasks/main.yml 


- name: install Ansible 


pip: name-ansible 


11.3 ”小结 


本 章 讲解 了 探讨 环境 搭建 流程 的 思路 以 及 目 动 化 搭建 环境 的 方法 。 

我 们 往往 觉得 环境 的 运行 没有 什么 技术 含量 ， 而 且 很 难看 到 付 诸 其 中 的 努力 。 但 是 ， 应 用 
能 持续 平稳 地 运行 ， 蝶 无 疑问 是 高 效 环 境 搭建 以 及 维护 的 功 表 。 

从 长 远 角 度 看 ， 搭 建 环境 的 自动 化 对 提高 搭建 环境 及 维护 的 效率 有 十 分 明显 的 效果 。 男 外 ， 
搭建 流程 自动 化 使 得 项 目 成 员 能 够 自由 地 搭建 个 人 开发 环境 ， 能 大 幅 提 高 整个 项 目的 生产 能 

此 推荐 各 位 搭建 环境 时 多 注意 稳定 和 高 效 两 个 方面 。 为 外 ， 为 了 让 项 目 稳 定 高 效 运 转 ， 
建议 导入 环境 搭建 的 日 动 化 。 




















自动 化 的 “ 度 ” 在 哪里 


当 我 们 为 实现 自动 化 而 写 搭建 流程 的 详细 列表 时 ， 会 发 现 搭 建 所 需 的 步骤 比 我 们 想象 中 要 
多 得 多 。 其 中 有 些 内 容 目 动 化 起 来 很 麻烦 ， 有 些 内 容 又 很 难 日 动 化 。 于 是 这 些 步 又 要 自动 化 到 
一 个 什么 “程度 ” 便 成 了 重要 的 研究 课题 。 

刚 开 始 导 入 上 自动 化 时 ， 看 到 服务 器 目 己 搭建 环境 ， 人 们 往往 会 得 意 筷 形 ， 希 望 把 所 有 步 又 
全 都 自动 化 。 然 而 我 们 认为 这 样 做 是 错 的 。Ansible 的 Playbook 虽然 能 极 简洁 地 描述 搭建 步 又， 
但 量 堆积 到 一 定数 量 同样 会 使 可 读 性 变 差 。shell 模块 确实 可 以 强行 自动 化 一 些 繁杂 的 步骤 ， 不 
过 日 后 读 和 改 的 时 候 上 朋 定 会 遇 到 麻烦 。 

我 们 认为 ， 简 化 流程 是 流程 自动 化 工作 的 一 部 分 。 大 部 分 自动 化 工具 都 把 构建 时 经 常 遇 到 
的 操作 进行 了 简化 ， 使 得 我 们 能 轻松 执行 这 些 操 作 ，Ansible 更 是 将 这 些 机 制 以 标准 模块 的 形式 
提供 给 了 我 们 。 难 以 用 这 些 标准 模块 实现 的 操作 可 以 认为 是 匈 余 的 或 者 是 错 的 ， 应 该 考虑 删除 
或 者 改良 。 有 些 时 候 ， 如 果 能 简化 流程 或 结构 ， 少 虑 改变 染 构 也 是 值得 的 。 

通过 目 动 化 实现 繁琐 的 搭建 流程 远 不 如 找 一 个 能 简单 完成 环境 搭建 的 方法 来 得 有 价值 。 因 
此 不 要 想 者 用 目 动 化 去 掩 兰 复 杂 的 操作 ， 而 是 要 以 目 动 化 为 女 机 着 手 改 善 流程 。 
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巧 用 备份 

搭建 环境 实现 目 动 化 后 ， 每 次 向 组 中 添加 服务 器 都 要 整体 从 零 搭 建 环境 。 但 是 ， 一 通电 重 
新 搭建 相同 结构 的 服务 器 是 一 件 非 常 浪费 时 间 的 事 。 如 果 我 们 采用 的 基础 设备 可 以 使 用 备份 或 
服务 器 和 镜像， 那么 直接 复制 现 有 的 服务 器 备份 要 远 比 重新 搭建 环境 轻松 且 安 全 。 

另外 ， 添 加 新 的 服务 器 组 时 ， 由 于 全 新 服务 器 中 不 存在 维护 用 户 ， 所 以 每 次 都 要 面 对 目 举 
问题 。 如 果 能 从 已 有 维护 用 户 的 状态 开始 搭建 ， 那 么 整个 过 程 将 轻松 不 少 。 

出 于 以 上 原因 ， 我 们 在 搭建 时 会 按照 下 述 方针 进行 备份 ， 缩 短 搭建 时 间 。 

: 在 执行 了 environ role 的 状态 下 做 一 次 备份 

' 基于 上 述 备份 给 每 组 里 的 每 一 台 服 务 器 搭建 环境 并 备份 ， 有 多 台 服 务 器 组 成 的 服务 器 组 基 

IP EMSERENE, 
虽然 看 服务 器 自动 搭建 环境 是 一 种 人 享受， 但 多 余 操作 还 是 应 该 尽量 减少 。 


第 12 章 应 用 的 性 能 改善 


使 用 Web 应 用 时 ， 随 者 访问 量 的 增加 ， 我 们 会 过 到 啊 应 延 返 、 请 求 失 败 无 法 正常 提供 服务 





本 章 我 们 先 学 习 上 述 问 题 的 应 对 方法 以 及 Web 应 用 /服务 器 的 性 能 评估 ， 然 后 阶段 性 地 导 
入 gunicorn 、nginx， 并 在 各 阶段 进行 性 能 评估 ， 观 察 性 能 改善 的 情况 。 

本 章 最 终 将 形成 如 图 12.1 所 示 的 服务 器 结构 。gunicorn fll nginx 的 相关 内 容 会 在 导入 时 详 
细 说 明 ， 这 里 不 作 深 入 了 解 。 




















e 


浏览 器 反 向 代理 服务 器 Web 应 用 服务 器 








12.1 nginx 与 gunicorn 的 协作 


NOTE 

所 谓 反 向 代理 ( Reverse Proxy )， 是 指 负 责 接收 随机 多 个 客户 疡 发 来 的 请 来 的 服务 器 ， 其 
目的 在 于 降低 特定 服务 恬 处 理 请 求 的 负担 或 向 指定 服务 器 群 分 配 访问 请 求 。 它 的 运作 方式 与 通 
SARERA a EER, EER RE, 


12.1 Web 应 用 的 性 能 


Web 应 用 负 合 过 重 时 会 产生 哪些 问题 ? 面 对 人 负 和 谷 过 重 应 采取 什么 对 策 ? 选择 对 策 时 又 应 该 
进行 哪些 考量 呢 ? 接 下 来 我 们 将 了 解 一 下 这 些 问 题 。 


12.1.1 Web 应 用 面 对 大 量 集中 请 求 时 会 产生 哪些 问题 


当 应 用 服务 胡 接 收 到 的 请 求 增 多 时 ， 如 果 一 个 请 求 尚 未 处 理 完 又 接 到 了 下 一 个 请 求 ( 即 两 
个 请 求 几 乎 同时 到 达 )， 那 么 后 一 个 请 求 将 被 加 入 队列 ， 等 待 前 一 个 请 求 处 理 完 毕 。 即 便 是 可 以 
并 行 处 理 多 个 请 求 的 服务 器 ， 一 旦 到 了 并 行 处 理 数 的 极限 ， 后 到 的 请 求 也 会 被 加 入 队列 ， 等 待 
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处 理 的 线程 将 越 来 越 多 。 

这 种 状态 会 使 应 用 服务 各 进入 高 负 答 状态 ， 出 现 CPU 负担 加 重 、 内 存 空间 不 足 等 问题 。 

高 负 何 状态 下 应 用 可 能 无 法 正常 运行 ， 或 者 性 能 出 现 明 显 下 降 。 以 第 2 草 中 编写 的 Web 应 
用 为 例 ， 这 个 应 用 在 Python 的 SimpleHTTPServer 模块 的 Web 应 用 服务 名 上 运行 ， 然 而 这 个 服 
务 从 是 单 进程 单线 程 的 ， 无 法 同时 处 理 多 个 请 求 。 因 此 请 求 集 中 到 达 时 等 竺 处 理 的 请 求 会 增多 ， 
应 用 性 能 会 下 降 。 

另外 ， 等 待 队列 也 是 有 上 限 的 ， 具 体 上 限 与 硬件 本 身 的 性 能 有 关 。 一 旦 等 竺 数 达 到 上 限 ， 
新 的 请 求 将 被 视 为 无 法 处 理 的 请 求 ， 表 现 为 切断 连接 ， 请 求 失败 。 另 外 ， 队 列 达 到 上 限 有 时 会 
造成 服务 硕 的 程序 异 稍 停止 ， 导 致 无 法 连接 服务 规 。 

这 些 问题 在 客户 问 会 表现 为 无 法 连接 、 反 应 慢 、 频 繁 报错 等 。 该 状态 会 影响 用 户 对 应 用 的 
正常 使 用 。 
































12.1.2. $1 8 fA far BOUT S 


FER ia ff Rp AA e a he HAE ES E? 

rea Gum] CS nf UAS JR ARR, A ERR NAA Eo Eun HRS aH] CPU 处 
理 能 力 不 足 了 ， 结 东 我 们 换 了 一 块 性 能 更 好 的 便 盘 ， 这 显然 无 法 解决 问题 。 

因此 要 明确 问题 所 在 ， 选 择 合适 的 对 策 。 下 面 是 几 种 典型 问题 及 其 对 策 。 








问题 解决 方法 
CPU 占用 率 高 增加 处 理 的 进程 和 线程 数 。 更 换 成 性 能 更 好 的 CPU 








硬盘 VO fer 优化 读 取 、 写 入 数据 的 方法 。 更 换 成 性 能 更 好 的 硬盘 。 
AFTE 释放 被 无 用 程序 占用 、 分 配 的 内 存 。 增 加 物理 内 存 。 











除 此 之 外 还 有 许多 解决 方法 ， 不 过 本 章 将 以 上 述 3 点 为 中 心 进 行 说 明 。 另 外 ， 为 提高 改善 
性 能 的 效率 ， 需 要 还 循 以 下 原则 。 








。 从 预期 效果 最 大 的 方法 开始 尝试 
e 从 所 需 资 金 、 步 纤 、 时 间 最 少 的 方法 开始 尝试 
。 实施 对 来 前 后 各 评 全 一 次 性 能 








第 一 条 “从 预期 效 末 最 大 的 方法 开始 尝试 ”是 因为 如 来 和 完 采 用 了 效 琳 较 小 的 方法 ,日 后 再 
采用 效 末 较 大 的 方法 时 ， 前 一 个 方法 的 效 来 会 被 履 盖 挥 ， 这 就 使 前 一 次 的 工作 成 了 无 用 功 。 

第 二 条 “从 所 需 资 金 、 步 又 、 时 间 最 少 的 方法 开始 答 试 ” 指 优先 选择 性 价 比 高 的 方法 ， 把 
成 本 高 成 效 低 的 方法 摆 到 次 要 位 置 。 
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第 三 条 “实施 对 末 前 后 各 评估 一 次 性 能 ”是 为 了 向 握 该 对 入 的 实际 效果 。 评 估 结 灯 能 明确 
告诉 我 们 成 本 换 来 多少 效果 。 


12.2 评估 留言 板 应 用 的 性 能 








本 节 ， 我 们 将 对 第 2 章 中 开发 的 应 用 进行 性 能 评估 ， 然 后 学 习 如 何 让 该 应 用 在 nginx 和 
gunicorn 上 运行 。 
12.2.1 什么 是 应 用 的 性 能 


我 们 总 是 会 次 “应 用 的 性 能 好 /不 好 ”， 但 好 与 不 好 完 竟 指 的 是 什么 呢 ? 下 面 是 几 个 性 能 好 
的 例子 。 











。 应 用 的 处 理 能 力 强 
。 内 存 占用 量 小 

。 页 面 显示 速度 快 
e. 通信 响应 速度 快 








这 些 评价 对 象 都 不 相同 ， 评 价 中 使 用 的 词语 也 是 强 、 小 、 快 ， 各 不 一 样 。 可 见 ， 应 用 的 性 
能 有 多 个 指标 。 所 以 在 谈论 性 能 时 ， 必 须 首 先 确 定 是 哪 方 面 性 能 ， 不 然 理解 上 就 会 出 现 偏差 。 

在 Web 应 用 的 各 项 性 能 指标 中 ， 本 章 将 重点 人 研究 从 发 送 HTTP 请 求 到 返回 啊 应 的 这 段 时 间 
( 即 啊 应 时 间 )。 啊 应 时 间 越 短 ， 浏 览 徊 切换 页 面 的 速度 就 越 快 ， 用 户 就 会 觉得 应 用 越 流 畅 。 力 
外 ， 我 们 在 评估 性 能 时 将 使 用 ApacheBench ( ab 命令 )。 这 是 一 球 基 准 测 试 工具 ， 能 简单 地 检测 
应 用 的 啊 应 时 间 和 请 求 成 功率 。 





12.2. ”安装 ApacheBench 


ApacheBench 是 Web Ik 3 $$ Apache Br? B) LE Z—o 3B nb apt HI cH], A a k 
apache-utils ( LIST 12.1 ). 


© LIST 12.1 通过 apt 进行 安装 


$ sudo apt-get install apache2-utils 


安装 完 后 就 能 使 用 ab 命令 了 。 本 章 使 用 的 是 ApacheBench 的 2.3 版 本 。 
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12.2.3 用 ApachBench 评估 性 能 


这 里 运行 第 2 草 中 开发 的 应 用 ,用 ap 命令 检测 啊 应 时 间 。 这 里 以 留言 板 首 页 的 啊 应 速度 
为 检测 对 象 。 我 们 和 希望 在 已 提 区 数据 的 状态 下 进行 检测 ， 因 此 事先 输入 了 50 条 数据 。 为 外 ， 应 
用 的 运行 环境 如 下 。 








Ubuntu 14.04 ( 64bit 版 ) 





Intel Core 2 Duo 2.2GHz ( 双核 ) 





512MB 


Js: Bt cJ 2] FHRCAS- 4% ( LIST 12.2 )。 


加 LIST 12.2 ”启动 应 用 


$ python guestbook.py 
s Running on hnttp://127.0.0.1:8000/ 


* Restarting with reloader 








使 用 screen 命令 的 情况 下 会 弹出 新 窗口 ， 在 新 窗口 中 执行 ab 命令 。 不 使 用 screen fi 
令 时 则 需要 按 Ctrl+Z 键 ， 将 运行 中 的 应 用 移 至 后 台 ， 然 后 再 执行 ab 命令 。 

应 用 可 以 通过 IP 地 址 127.0.0.1、 端 口号 8000 访问 ， 所 以 ab 命令 要 指定 这 个 URL (LIST 
12.3 )。-n 选项 可 以 指定 请 求 次 数 ，-c 选项 可 以 指定 连接 数 。 这 里 我 们 把 总 计 1000 次 请 求 分 100 
个 连接 并 行 发 送 。 
EjLIST123 执行 ab 命令 


5$ ab -=m 1000 -e 100 heto: /27.0.0.158000/ 
检测 结束 后 会 输出 如 LIST 12.4 所 示 的 报告 。 


B LIST 12.4 ab 命令 的 结果 


Server Software: Werkzeug/0.9.6 
Server Hostname: T2900: 1 
Server Port: 8000 

Document Path: / 

Document Length: 7398 bytes 
Concurrency Level: 100 

Time taken for tests: 4.911 seconds 
Complete requests: 1000 


Failed requests: 0 
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Write errors: 0 

Total transferred: 7554000 bytes 

HTML transferred: 7398000 bytes 

Requests per second: 203.61 [#/sec] (mean) 

Time per request: 491.146 [ms] (mean) 

Time per request: 4.911 [ms] (mean, across all concurrent requests) 
Transfer rate: 1501.99 [Kbytes/sec] received 


Connection Times (ms) 


min mean[-«/-sd] median max 


ORG 0 0 D 0 5 
Processing: i® 466 82.5 489 497 
Waiting: ]9- 42660 782.5 489 497 
TOTEL 3 24 467 481.5 489 497 


Percentage of the requests served within a certain time (ms) 


50$ 489 

66$ 490 

75% 491 

80% 491 

90% 492 

95% 496 

98% 497 

995 497 
100% 497 (longest request) 


接 下 来 了 解 一 下 检测 结果 中 需要 注意 的 地 方 。 


€ Complete requests 
Complete requests 部 分 显示 了 请 求 成 功 与 失败 的 情况 。 通 过 上 面 的 例子 ， 我们 可 以 看 到 ， 
1000 个 请 求全 部 成 功 。 如 果 请 求 没有 全 部 成 功 ， 表 示 可 能 超出 了 Web 服务 各 的 处 理 能 














Complete requests: 1000 


Failed requests: 0 


€ Requests per second 


1 秒 处 理 的 请 求 数 。 下 述 结 果 表 示 每 秒 大 约 处 理 203 个 请 求 。 








Requests per second: 203.61 [#/sec] (mean) 
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€) Connection Times 

Connection Times 部 分 可 以 查看 处 理 1 个 请 求 所 需 的 连接 时 间 (Connect )、 处 理 时 间 
( Processing )、 等 待 时 间 (Waiting )， 单 位 精确 到 毫秒 。 各 列 元 素 分 别 代表 最 小 值 (min )、 
平均 值 (mean )、 标 准 差 ( [+/-sd] )、 中 间 值 (median )、 最 大 值 ( max )。 如 果 某 个 时 间 存 在 
明显 的 不 平均 现象 ， 证 明 应 用 的 某 个 部 分 有 可 能 存在 瓶 贷 。 

以 下 述 执行 结果 为 例 ， 我 们 是 在 本 地 环境 中 连接 本 地 的 Web 应 用 ， 所 以 连接 时 间 非 常 短 。 
另外 ， 处 理 时 间 和 等 待 时 间 都 没有 明显 的 不 平均 现象 ,证 明 应 用 中 不 存在 瓶颈 。 

















Connection Times (ms) 


min mean[-«/-sd] median max 


Connecti 0 0 I 0 5 
Processing: 19 466 682.5 489 497 
Waiting: 1O 56 07 825 489 497 
TOGAL g 24 467 81.5 489 497 





我 们 的 这 个 留言 板 应 用 直接 使 用 了 Flask 内 置 的 HITP 服务 硕 。 该 内 置 HTTP Jl AS 4r HH 
Python 标准 模块 的 HTTPServer 类 扩展 而 来 。 这 个 服务 器 并 不 算 特 别 慢 ， 但 如 果 导 和 人 更 高 速 的 
Python 专用 应 用 服务 硕 ， 将 能 明显 改善 啊 应 性 能 。 

接 下 来 我 们 将 导入 gunicorn， 看 看 这 个 Python Bri] Web 应 用 的 HTTP 服务 融 是 如 何 改 善 
啊 应 性 能 的 。 














NOTE 

本 章 用 ApacheBench 评估 了 应 用 的 性 能 ， 但 要 注意 ， 这 与 Web 应 用 实际 运作 时 的 情况 不 
完全 相同 。 

ApacheBench 的 评估 对 象 是 单一 URL， 但 一 般 的 Web 应 用 除 HTML 以 外 还 需要 对 图 片 、 
CSS. JavaScript 文件 发 送 请 求 。 要 获取 某 URL 页 面 中 的 所 有 元 素 ， 有 时 需要 几 十 个 请 求 。 
此 各 位 要 记 住 ，ab 命令 检测 出 的 响应 性 能 与 用 户 体感 的 响应 时 间 之 间 是 存在 差异 的 。 


12.3 gunicorn 简介 


gunicorn 是 面向 Python WSGI 应 用 的 HTTP IKI fo CE Linux/Unix 上 运行 ， 优 点 是 轻 量 
级 上 且 速度 快 。gunicorn 通过 一 个 控制 进程 和 多 个 工作 进程 来 执行 应 用 程序 。 由 于 它 是 一 个 
Python 模块 ， 所 以 可 以 变更 工作 进程 的 类 以 及 扩展 服务 硕 本 刁 。 
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12.3.1 Z% gunicorn 
gunicorn 可 以 用 pip 命令 安装 (LIST 12.5 )。 


© LIST 12.5 用 pip 命令 安装 


$ pip ingrtall crm ce 


通过 上 述 方法 安装 gunicorn 后 ， 就 可 以 使 用 gunicorn 命令 了 。 


12.3.2 在 gunicorn 上 运行 应 用 
首先 设置 一 个 工作 进程 ， 运 行 应 用 (LIST 12.6 )。 


© LIST 12.6 用 gunicorn 命令 运行 留言 板 应 用 


$ gunicorn -w 1 -9 127.0.0.1:8000 guestbook 


我 们 在 这 个 状态 下 再 执行 一 次 ab fg m, MARAU F o 


Server Software: gumicorn/19.,1,1 
SGEPVerSiostudne- WA O O i 

Server POCE sg 8000 

Document Path: "i 

Document Length: 7398 bytes 

Concurrency Level: 100 

Time taken for tests: 4.469 seconds 

Complete requests: 1000 

Failed requests: 0 

Write errors: 0 

Total transferred: 7560000 bytes 

HTML transferred: 7398000 bytes 

Requests per second: 223.75 [#/sec] (mean) 

Time per request: 446.937 [ms] (mean) 

Time per request: 4.469 [ms] (mean, across all concurrent requests) 
Transfer rate: 1651.87 [Kbytes/sec] received 


Connection Times (ms) 

min mean[+/-sd] median max 
Conaect 0 Jb SS 0 8 
Processing: 31 424 71.7 444 462 
Waiting: 14 424 71.8 443 462 


Het ue 


Percentage of the requests served within a certain time 


50$ 


100% 


可 以 看 到 与 之 前 用 Flask NEII eT BIER AR 2E AE e 


由 于 当前 运行 应 用 的 虚拟 机 的 CPU 数 设 置 为 2， 


444 
444 
444 
444 
445 
445 
446 
446 


469 (longest request) 


资源 。 所 以 进程 数 应 至 少 设置 为 2。 


于 是 我 们 将 gunicorn 的 工作 进程 设置 为 2， 


选项 指定 ( LIST 12.7 )。 


回 LIST 12.7 用 gunicorn 命 


Server Software: 


Server Hostname: 


Server Port: 


Document 


Document 


Path: 
Length: 


Gonouncene need 


Time taken for tests: 


Complete 


requests: 


Failed requests: 


Write errors: 


Total transterred: 


HTML transferred: 


Requests 
Time per 
Time per 


Transfer 


per second: 
request: 
request: 


rate: 


444 469 


行 应 用 ( 工作 进程 数 为 2 ) 


$s gunicorn -w 2 -o 127,0.0.1:8000 guestbook 


检测 结 来 如 下 。 


cgunicormn/19.1,1 


127-00, TE 
8000 

" 

7398 bytes 
100 


2.376 seconds 
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(ms ) 


因此 单独 一 个 工作 进程 无 法 充分 利用 CPU 


再 次 执行 ab 命令 进行 检测 。 工 作 进 程 数 用 -w 


1000 

0 

0 

7560000 bytes 

7398000 bytes 

420.91 [t/sec] (mean) 

237.582 [ms] (mean) 

2.376 [ms] (mean, across all concurrent requests) 
3107.48 [Kbytes/sec] received 
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Connection Times (ms) 


min mean[-«/-sd] median max 


Connect: 0 JE IRG 0 7 
Processing: 1e 225 37.3 235 248 
Waiting: 157 E Ps NEL STI NS 247 
TOTEL 3 db 226 35-8 25 252 


Percentage of the requests served within a certain time (ms) 


503% 235 
66$ 236 
75% 236 
80% 236 
90% 236 
955 237 
98% 238 
99% 238 
100% 252 (longest request) 


平均 啊 应 时 间 缩 短 了 40%， 可 见 速 度 快 了 许多 。 接 下 来 我 们 再 看 看 用 作 Web 服务 硕 和 代理 
服务 需 的 nginx。 


12.4 nginx 简介 


nginx ( Engine X ) ”是 Nginx Inc. 开发 的 Web 服务 器 ,拥有 HTTP 服务 器 、 代 理 服 务 器 等 功 
能 ， 轻 量 级 日 速度 快 。 

近年 来 nginx 成 长 迅速 ， 在 Web 服务 絮 界 占有 的 份额 仅 次 于 Apache、 IIS (Internet 
Information Services )， 居 世界 第 三 ( 约 14% ), 一 些 较 大 规模 的 Web 服务 也 采用 了 nginx， 比 如 
WordPress.com”, GitHub”, Instagram” da 





12.4.1 ZÆ nginx 
nginx 的 安装 可 以 直接 从 源码 构建 ， 不 过 由 于 Ubuntu 的 版 本 库 中 有 相关 程序 包 ， 所 以 我 们 





http://nginx.org;/ 
https://wordpress.com/ 
httpbei/lgithub.com/ 


€) ONO 


http://instagram.com 
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用 apt-get áp S FTT XA ( LIST 12.8 )。 


© LIST 12.8 安装 nginx 


$ sudo apt-get install nginx 


本 书 使 用 了 nginx 的 1.4.6 版 本 ( LIST 12.9). 


© LIST 12.9 查看 版 本 
$ nginx -v 


nginx version: nginx/1.4.6 (Ubuntu) 


局 动 、 停 止 等 操作 通过 service 命令 实现 (LIST 12.10 ~ LIST 12.13 )。 


© LIST 12.10 JAZ) nginx 


$ sudo service nginx start 


加 LIST 12.11 停止 nginx 


$ sudo service nginx stop 


Ej LIST 12.12 ”重启 nginx 


$ sudo service nginx restart 


Ej LIST 12.13 Æt nginx 


$ sudo service nginx reload 





测试 设置 文件 是 否 有 错时 ， 执 行 配 置 测 试 ( ConfigTest ) ( LIST 12.14 ). 


EJ LIST 12.14 nginx 的 配置 测试 


$ gudo nging t 


12.4.2 ”检测 nginx 的 性 能 


前 面 我 们 检测 了 留言 板 应 用 的 性 能 ， 现 在 我 们 看 看 Web 服务 硕 nginx 本 里 的 性 能 如 何 。 

由 于 要 运行 默认 站 点 ， 所 以 这 里 我 们 先 用 管理 员 权 限 编 辑 设置 文件 /etc/nginx/sites-available/ 
default ( LIST 12.15 )。 如 有 果 Apache 等 已 安装 的 软件 已 经 占用 了 问 口 80， 则 需要 将 listen 后 的 端 
口号 修改 成 其 他 数值 。 











© LIST 12.15 /etc/nginx/sites-available/default 
server { 
listen 80; # 使 用 端口 80 
server name localhost; # 主机 名 为 localhost 
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# 访问 日 志 的 文件 路 径 


access log  /var/log/nginx/localhost.access.log; 


location / ( # 域名 后 的 路 径 为 / 时 
root /var/www; # REX 
index index.html index.htm; 4 E S 汪 


这 里 不 存在 已 设置 好 的 根 目 录 /var/www 时 ， 需 要 手动 创建 ( LIST 12.16 )。 


加 LIST 12.16 创建 /var/www 目录 


$ sudo mkdir /var/www 


$ sudo chown www-data:www-data /var/www 


用 管理 员 权 限 生 成 用 于 默认 站 点 的 目录 (LIST 12.17 )。 


本 LIST 12.17 /var/www/index.html 
ehtml- 
<head> 


«meta http-equiv="Content-type" content="text/html 
«title» 测试 页 面 </title> 
</head> 


; Charset=utf-8"> 


EOS 
«h1» 测试 页 面 </h1> 
«/body» 
</html> 


另外 ， 有 时 候 我 们 会 遇 到 工作 进程 数 软 认为 1 的 情况 ， 所 以 要 根据 CPU 数 ( 核 心 数 ) 修 
改 /etc/nginx/nginx.conf 的 worker processes。 这 里 我 们 设置 为 2 ( LIST 12.18 )。 


© LIST 12.18  /etc/nginx/nginx.conf 


user www-data; 


woulsena FOSSE 


# PE 








编辑 完成 后 执行 配置 测试 ， 确 认 没 有 问题 后 重 载 或 重启 nginx( LIST 12.19 )。 


Ej LIST 12.19 nginx 的 配置 测试 与 重 载 
$ sudo nginx -t 
the configuration file /etc/nginx/nginx.conf syntax is ok 


configuration file /etc/nginx/ngriuxeeonf test is successful 


$ sudo service nginx reload 


* Reloading nginx configuration nginx 


接 下 来 用 ApacheBench 评估 性 能 ( LIST 12.20 )。 


& LIST 12.20 执行 ab 命令 


$ ab -m 1000 -e 100 http: /127.0.0.1/ 


评 佑 结果 如 下 。 


Server Software: 
Server Hostname: 


Server Port: 


Document Path: 


Document Length: 


Gomme ls: 
Time taken for tests: 
Complete requests: 
Failed requests: 
Write errors: 

Total transferred: 
HTML transferred: 
Requests per second: 
Time per request: 
Time per request: 


Transfer rate: 


Connection Times (ms) 


nginz/i. 4.6 
WAT Oa 0 
80 


/ 
194 bytes 


100 

0.214 seconds 

1000 

0 

0 

404000 bytes 

194000 bytes 

4662.92 [t/sec] (mean) 
21.446 [ms] (mean) 
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0.214 [ms] (mean, across all concurrent requests) 


1839.67 [Kbytes/sec] received 


min mean[+/-sd] median max 


connecti 0 9 
Processing: 1 L2 
Waiting: 1 10 
Moreni LI NI 


Percentage of the requests 


50$ 2I 
66$ 21 
75$ 2d 
80$ ZH 
90$ 23 
95S 26 


98$ PiS 


zur 10 JEJE 
ome LI 26 
4.1 9 25 
2 o 9 zu 29 


served within a certain time 
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995 29 
100% 29 (longest request) 


与 gunicorn 上 运行 的 留言 板 相 比 ， 啊 应 速度 快 出 了 一 个 层级 。 


12.5 在 nginx 和 gunicorn 上 运行 应 用 





现在 在 gunicorn 上 运行 留言 板 应 用 ， 然 后 通过 nginx 进行 反问 人 代理， 返回 啊 应 。 通 过 反问 
代理 啊 应 可 以 将 留言 板 应 用 的 服务 融 模 加 扩展 成 多 个 。 这 里 我 们 不 进行 枝 和 癌 扩 展 ， 只 评 佑 单一 
服务 硕 的 应 用 性 能 。 





12.5.4 gunicorn 的 设置 
gunicorn 可 以 指定 -D 选项 将 进程 转 为 守护 进程 ， 即 守护 进程 化 ( Daemonize ) ( LIST 12.21 )。 


© LIST 12.21 通过 gunicorn 命令 将 留言 板 应 用 转 为 守护 进程 并 执行 


$ gunicorn -w 2 -b 127.0.0.1:8000 -D guestbook 


NOTE 

守护 进程 化 是 指 以 Unix 守护 进程 的 形式 运行 程序 。Unix 守护 进程 运行 在 后 合 ， 并 且 启 动 之 
后 不 需要 用 户 直 接 控制 。 

以 gunicorn 为 例 ， 给 gunicorn 命令 指定 -D 选项 后 ，gunicorn 便 脱 离 了 用 户 的 控制 ， 会 
转 为 持续 等 得 请 来 的 后 人 进程 6 


12.5.2 nginx 的 设置 


编辑 nginx 默认 站 点 的 设置 文件 ， 以 反 回 代理 的 形式 连接 在 gunicorn 上 运行 的 应 用 (LIST 
i202) 


© LIST 12.22 /etc/nginx/sites-available/default 
# 名 为 guestbook 的 upstream (上游 服务 器 ) 的 设置 


upstream guestbook { 


局 全 下 VS 人 由 327 0.0 188000 


j 


server { 
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listen 80; # 使 用 端口 80 
server name localhost; # 主机 名 为 1ocalhost 
# 访问 日 志 的 文件 路 径 


access log  /var/log/nginx/localhost.access.log; 


location / { # 域名 后 的 路 径 为 / 时 
# 反问 代理 到 名 为 guestbook 的 upstream 
proxy pass http://guestbook; 





upstream 指令 里 可 以 设置 多 个 服务 硕 。 在 一 台 应 用 服务 融 无 法 满足 处 理 需求 时 ， 可 以 在 
upstream Hii rZ $1 HH er soe HH fA; 
设置 文件 编辑 完成 后 要 记得 进行 配置 测试 及 重 载 。 








12.5.3 评估 nginx+gunicorn 的 性 能 
接 下 来 用 ApacheBench 评估 性 能 ( LIST 12.23 )。 


回 LIST 12.23 ”执行 ab 命令 


S$ as =n 1000 -=&@ 100 ntEtBs//127.0.0.1/ 


评 佑 结 灯 如 下 。 


Server Software: 
Server Hostname: 


Server Port: 


Document Path: 


Document Length: 


Concurrency Tevel: 


Time taken for tests: 


Complete requests: 
Failed requests: 
Write errors: 

Total transferred: 
HTML transferred: 
Requests per second: 
Time per request: 
Time per request: 


Transfer rate: 


nginz/l. 4.6 


127-00. 1 
80 

" 

7398 bytes 
100 


2:6055 EGIDIUS 

1000 

0 

0 

7556000 bytes 

7398000 bytes 

376.61 [t/sec] (mean) 

265.529 [ms] (mean) 

2.655 [ms] (mean, across all concurrent requests) 


2778.95 [Kbytes/sec] received 
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Connection Times (ms) 


min mean[-«/-sd] median max 


Connecti: 0 T S36 0 14 
Processing: 2 2520042%2 264 2m» 
Waiting: 22m be qo 264 273 
morani: 27 253 39.8 264 286 


Percentage of the requests served within a certain time (ms) 


50% 264 
66$ 265 
75% 265 
80% 265 
90% 266 
955 266 
98% 267 
99$ 268 
100% 286 (longest request) 


与 单独 由 gunicorn HARRIS AE, mM KA ERK, BAE HE GC A 
RIAH, ARAR n ARS 





12.5.4 性 能 比较 


最 后 我 们 来 比较 
12.25 所 示 。 





下 改善 前 和 改善 后 的 性 能 评估 结果 。 评 佑 结果 如 LIST 12.24 fll LIST 


© LIST 12.24 改善 前 的 评估 结果 ( 精 选 ) 


Connection Times (ms) 


min mean[+/-sd] median max 


connec: 0 0 desde 0 5 
Processing: 19 466 82.5 489 497 
Waiting: L9 A66 62.5 489 497 
Morani: 24. 467 481.5 489 497 


© LIST 12.25 改善 后 的 评估 结果 ( 精 选 ) 


Connection Times (ms) 


min mean[-«/-sd] median max 


Com er 0 JL 2 ut 0 14 
Processing: 2A 252 42.2 264 2/3 
Waiting: Qo 252 cd 2 264 273 
Jota 27 253 39.8 264 286 
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从 Flask 的 开发 服务 融 换 到 nginx 和 gunicorn 组 成 的 服务 兹 之 后 ，Total 的 时 间 比 改善 前 缩 
短 了 近 一 半 。 啊 应 时 间 缩 得了 ， 因 此 我 们 可 以 认为 有 改善 效果 。 至 此 改善 工作 结束 。 











NOTE 

若 想 在 上 述 基础 上 进一步 缩短 响应 时 间 ， 可 以 考虑 下 述 对 策 。 出 于 篇 幅 原 因 ， 这 里 就 不 进 
行 详细 说 明了 。 

数据 库 方 面 将 shelve 换 成 MySOL 等 REBMS ( 加 快 数据 库 访问 速度 ) 

: 在 别 的 机 器 上 运行 应 用 ， 增 加 机 器 数 ( 增加 可 同时 处 理 的 请 求 数 ) 

: 使 用 memcached 等 缓存 服务 器 ( 减少 访问 数据 库 的 次 数 ) 


12.6 小结 











本 章 首 先 讲 了 对 Web 应 用 集中 访问 时 会 产生 的 服务 需 负 担 加 重 、 应 用 运行 不 稳定 等 问题 。 

接 下 来 介绍 了 该 类 问题 的 解决 方法 以 及 性 能 的 概念 ， 并 用 ApacheBench 对 第 2 章 中 开发 的 
Web 应 用 进行 了 性能 评估 。 男 外 ， 还 讲解 了 如 何在 gunicorn 这 一 应 用 服务 右上 运行 Web MH, 
以 及 如 何 设 置 nginx 用 作 反 向 代理 。 

改善 性 能 的 目的 是 让 已 有 系统 的 性 能 最 优化 。 然 而 ， 在 我 们 花 大 块 时 间 一 次 次 寻求 改善 时 ， 
会 发 现 新 解决 方案 的 效果 总 是 越 来 越 小 。 因 此 ， 改 善 性 能 之 前 要 先 定 一 个 性 能 的 目标 值 ， 确 定 
要 花 多 少时 间 来 做 这 件 事 。 关 手 改 善 前 切记 要 先 对 现 有 系统 进行 评 佑 ， 通 过 比较 确定 目标 。 选 
一 个 合适 的 目标 ， 用 最 少 的 时 间 和 资源 完成 最 优化 工作 ， 这 才 是 我 们 追求 的 高 效 的 性 能 改善 。 
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第 4 部 分 的 内 容 与 团队 开发 、 正 式 环 境 等 话题 相对 独立 。 这 里 将 介绍 完成 集 
成 测试 之 后 的 测试 思路 、 在 Django 上 进行 开发 时 需要 注意 的 信息 、 方 便 好 用 的 
Python 库 等 内 容 。 


第 13 章 让 测试 为 我 们 服务 
第 14 章 ”轻松 使 用 Django 


第 15 章 方便 好 用 的 Python 模块 
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不 知 各 位 在 开发 过 程 中 有 没有 过 到 过 下 述 情 况 。 








e 没有 明确 的 目标 ， 只 能 摸索 春 进行 开发 ， 最 后 成 品 与 原 定 的 需求 不 待 ， 导 致 整个 推翻 





重 做 
e 程序 严格 按照 设计 书 实现 ,但 在 集成 测试 阶段 发 现 其 与 周边 功能 结合 不 到 一 起 ， 导 人 怪 故 
障 频 出 





本 章 将 把 测试 的 观点 引入 开发 的 各 个 过 程 之 中 ， 为 解决 或 规避 开发 中 出 现 的 上 述 问题 提供 
解决 方案 。 我 们 希望 本 草 内 容 能 让 各 位 从 开发 初级 阶段 开始 就 知道 宽 要 莱 顾 测试 ， 明 日 日 已 第 
要 考虑 什么 ， 需 要 杂 眼 确认 什么 ， 为 各 位 的 整个 开发 过 程 融 来 帮助 。 


NOTE 
本 书 的 中 心 内 容 是 编程 技法 ， 因 此 不 对 各 个 测试 所 用 的 手法 进行 具体 讲解 。 测 试 手法 的 相 
关内 容 有 许多 优秀 的 专业 书籍 可 供 参 考 ， 有 兴趣 的 读者 不 妨 一 试 。 
《软件 测试 的 艺术 》( 机 械 工业 出 版 社 ，2012 年 ) 
(软件 测试 PRESS 合集 》 ( 技术 评论 社 ，2011 年 ) 


13.1 认识 现状 : 测试 的 客观 环境 


在 各 位 所 处 的 环境 中 ， 测 试 处 于 怎样 一 个 地 位 呢 ? 

在 从 确认 运行 状况 到 进行 系统 测试 的 过 程 中 ， 各 个 阶段 都 花 大 把 时 间 去 测试 吗 ? 还 是 在 编 
码 结束 后 只 简单 确认 一 下 运行 状况 就 发 布 了 呢 ? 又 或 者 是 仔细 编写 测试 代码 ， 但 却 尽 量 控制 手 
动 测试 呢 ? 

细 化 到 各 个 测试 阶段 来 说 ， 由 于 项 目的 性 质 、 交 付 对 象 /搭档 /经 理 的 方针 等 因素 的 影响 ， 
很 多 时 候 我 们 不 能 选择 最 合适 的 工作 流程 ， 所 以 时 间 安 排 往往 不 尽 如 人 意 。 男 外 ， 就 算 日 程 表 
已 经 制定 好 ， 某 些 时 间 安 排 也 会 因 各 种 情况 而 缩短 其 至 删除 。 

所 以 很 多 时 候 我 们 心里 明白 测试 的 重要 性 ， 却 实在 挤 不 出 时 间 给 测试 。 对 于 需要 赶 工 的 项 
目 而 言 更 是 如 此 。 面 对 火烧 眉毛 的 日 程 表 ， 我 们 往往 会 失去 方向 ， 不 知道 该 从 哪里 下 手 。 


























D A&S2£3[v7h"vzy-TALHPRESS£844& ] ， 暂 无 中 文 版 。 一 一 编者 注 
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13.2 ”将 测试 导入 开发 各 个 阶段 


项 目 开始 之 后 ， 为 了 能 尽 可 能 高 效 地 完成 开发 的 各 阶段 ， 即 便 时 间 再 么 ， 也 要 尽早 将 测试 
的 观点 引入 项 目 之 中 。 因 为 随 着 开发 流程 的 推进 ， 修 改 、 变 更 都 会 越 来 越 难 。 

这 就 像 身 处 一 个 阳 生 的 环境 ， 只 要 在 行动 前 和 确认 一 下 地 图 ， 了 解 当 前 地 点 和 目的 地 的 位 
置 ， 之 后 就 基本 不 会 走 俩 。 即 便 方 回 略 有 偶 差 ， 只 要 能 在 转 第 一 个 付 时 及 时 发 现 ， 我 们 依然 能 
很 快 返 回 出 发 点 。 也 就 是 说 ， 如 末 途 中 能 每 到 一 个 路 口 都 确认 一 下 ， 承 算 其 间 走 错过 一 条 路 ， 
我 们 也 能 很 快 折 返 或 者 在 下 一 个 路 口 修 正方 向。 但 是 ， 如 于 行动 前 不 作 任何 确认 ， 等 上 固 月 乱 撞 
地 跑 到 了 其 他 城市 才 意 识 到 走 错 了 路 ， 此 时 再 回 过 头 来 看 地 图 就 为 时 已 晚 了 。 到 了 这 个 地 步 ， 
不 但 自前 走 找 不 到 目的 地 ， 就 连 折 人 运 也 很 难 返 回 出 发 太 ， 进 退 两 难 。 这 在 系统 开发 上 也 是 同样 
道理 ， 我 们 开始 项 目 之 前 必须 正确 理解 项 目的 前 提 条 件 和 目的 ， 尽 量 在 初期 阶段 及 早 发 现 错误 ， 
EEA I. 

AIL. MRAR, MenM HaEX— Tubs. AER RLE P AA 3L 
离 该 状态 的 元 素 并 对 其 加 以 改善 。 将 测试 的 观点 从 程序 测试 阶段 扩展 至 需求 定义 和 设计 阶段 ， 
这 能 有 效 地 帮助 我 们 在 开发 初期 修正 错误 。 

接 下 来 我 们 按照 开发 流程 一 步 步 进行 了 解 。 


























13.2.1 文档 的 测试 ( 审查 ) 


文档 类 的 测试 一 般 称 为 审查 (Review )， 它 也 是 测试 的 一 种 。 认 真 进行 审查 能 防止 因 理 解 仿 
差 而 导致 的 返工 或 者 不 小 心 实现 了 多 余 内 容 等 问题 。 因 此 即便 没有 充足 时 间 去 单独 审查 每 个 文 
档 ， 也 要 在 开始 实现 或 测试 设计 之 前 简单 地 将 文档 重新 审视 一 过 。 

文档 可 分 为 很 多 种 ， 比 如 下 面 这 些 。 





【 主要 文档 类 型 】 

。 和 需求 说 明 

e 需求 定义 

。 基本 设计 

e 详细 设计 

e ER KI 

e 数据 表 定 义 

e. 测试 说 明了 或 测试 设计 等 














文档 大 致 可 分 为 三 大 类 ， 一 是 确定 开发 方 回 的 文档 (需求 说 明 、 需 求 定义 等 )， 二 是 指导 具体 
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实现 的 文档 (基本 设计 、 详 细 设计 等 )， 三 是 规定 数据 使 用 方式 的 文档 ( ER 图 、 数 据 表 定义 等 )。 
下 面 是 审查 文档 时 经 稼 发 生 的 问题 。 








【问题 】 

e 文档 没有 更 新 ， 内 容 陈 旧 

e 未 指明 未 确定 的 事项 

。 摘 述 含糊 不 清 

e 存在 多 个 相同 标题 的 文档 文件 ， 捅 不 清 哪个 才 是 最 新 的 





对 于 内 容 陈旧 的 文档 ， 只 能 随 发 现 随 更 新 ， 然 后 定期 重审 ， 没 有 其 他 办 法 。 而 其 他 问题 客 
是 有 改善 余地 的 ， 下 面 我 们 来 一 个 个 解决 。 


€ 未 确定 的 事项 标明 “未 确定 

文档 是 担保 程序 以 及 测试 正确 性 的 重要 指标 ， 因 此 其 内 容 务 必 准 确 详实 ,不 能 有 遗漏 ， 也 
不 能 有 和 多余 内 容 。 

拿 到 文档 时 ， 不 要 百 接 劲 手 开 工 ， 先 从 头 到 尾 通 读 一 志文 要 ， 把 其 中 有 疑问 的 地 方 和 不 清 
楚 的 地 方 记录 下 来 。 特 别 是 在 项 目 刚刚 开始 的 阶段 ， 茶 些 需 求 和 规定 还 很 模糊 。 此 时 要 把 不 明 
确 的 部 分 找 出 来 ， 在 对 象 文档 里 注 明 “未 确定 ”"。 明 确 未 确定 的 项 目 是 对 残留 的 每 确定 项 目的 一 
种 可 视 化 ， 让 我 们 能 直观 地 看 到 哪里 还 有 竺 确定 的 项 目 。 想 消除 文档 的 遗漏 、 缺 失 等 问题 ， 这 
种 可 视 化 必 不 可 少 。“ 不 清 芍 还 有 哪些 不 清楚 的 事 ” 的 情况 必须 尽早 解决 。 记 录 未 确定 项 目 时 可 
以 同时 将 确定 该 项 目 所 需 的 条 件 写 下 来 ， 便 于 重审 文档 时 确认 是 否 需要 处 理 该 项 目 。 

羽 外 ， 碍 找 文档 漏 记 了 哪些 内 容 其 实 是 一 个 难度 很 高 的 工作 ， 这 里 介绍 两 种 行 之 有 效 的 方法 。 

一 种 是 对 比 上 一 阶段 的 文档 ， 查 看 内 容 是 否 有 遗 活 。 由 于 当前 阶段 文档 全 部 源 于 前 一 阶段 
文档 ， 所 以 二 者 内 容 出 现 不 吻合 时 ， 可 以 认为 文档 某 处 存在 遗漏 。 

男 一 种 是 将 功能 、 页 面 、 数 据 等 方面 有 关联 的 文档 放 在 一 起 ， 看 它们 之 间 是 否 存在 矛盾 。 
如 条 对 比 文档 时 出 现 内 容 不 揽 合 的 情况 ， 那 么 文档 茶 处 很 可 能 存在 问题 。 


























[ 消除 不 明确 的 点 】 

e 存在 未 确定 的 事项 时 ， 在 对 应 文档 内 标明 “未 确定 ” 

e 标注 “未 确定 ”的 同时 记录 确定 所 需 的 条 件 

。 查看 前 一 阶段 的 文档 ， 确 认 项 目 是 否 存在 遗漏 

e 检查 功能 、 页 面 、 数 据 等 方面 的 关联 ， 确 认 各 部 分 关联 正常 














© 摘 述 时 尽量 避免 收 义 
如 有 果 阅 读 文 档 时 发 现 内 容 存 在 模糊 不 清 的 地 方 ， 证 明 我 们 对 正确 的 内 容 的 定义 还 不 够 明确 。 
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e 在 表达 同一 个 事物 时 用 了 不 同 说 法 ( 用 语 不 一 致 ) 

“OO 等 "”“OO 左 右 ” 等 需要 清单 化 的 部 分 表述 含糊 不 清 

e 数值 增 减 的 幅度 、 上 下 限 不 明 (比如 写 1 ~ 10, 看 的 人 不 清楚 是 按 1、2、3… 还 是 按 1.0、 
1.1、1.2… 的 规律 变化 ) 

。 能 数值 化 、 符 号 化 的 内 容 却 用 文学 描述 (大 于 ~ 、~ 以 上 、 不 足 ~ 等 ) 








到 了 实现 阶段 ， 这 类 描述 难免 被 开发 者 加 入 个 人 的 理解 ， 产 生 歧 义 ， 进 而 导致 最 后 成 品 与 
我 们 想 要 的 东西 不 一 致 。 

若 想 改善 上 述 情况 ， 首 先 要 将 表达 同一 个 事物 的 用 语 统一 ， 坚 决 不 用 其 他 说 法 来 表述 该 事 
物 。 用 语 的 统一 能 带 来 认 知 的 统一 。 需 要 清单 化 的 东西 一 定 要 清单 化 ， 明 确 描 述 出 所 有 项 目 。 
清单 最 好 集中 写 在 一 处 ， 其 中 在 需要 参考 某 些 资料 的 部 分 写 明 相应 资料 的 位 置 ， 以 便 将 来 出 现 
变更 时 能 轻松 修改 。 

数值 增 减 的 幅度 、 上 下 限 也 要 尽量 写 明 。 因 为 它 会 给 是 否 限制 输入 内 容 、 项 目的 显示 宽度 
等 设计 方面 市 来 影响 。 

能 数值 化 、 符 号 化 的 东西 尽量 用 数值 、 符 号 来 表达 ， 不 要 用 文字 描述 。 因 为 文字 描述 更 容 
DT EREE o 

为 避免 开发 者 加 入 个 人 的 理解 ， 写 文档 时 应 避免 加 入 多 余 内 容 ， 同 时 要 将 必 备 内 容 表 述 得 
尽量 清楚 。 在 发 现 模棱两可 的 表述 时 ， 如 果 只 是 单一 的 局 部 问题 ， 我 们 只 需 即 刻 通 知 其 他 相关 
的 开发 人 员 ， 对 该 部 位 进行 修正 即 可 。 但 是 当 发 现 该 问题 散布 在 文档 各 处 时 ， 就 要 提起 注意 了 。 
首先 查看 手头 的 其 他 文档 ， 如 果 这 些 文档 也 有 同样 问题 ， 说 明 编 写 文档 的 前 期 讨论 做 得 不 够 充 
分 。 此 时 需要 警示 项 目 中 的 所 有 人 员 ， 因 为 该 问题 搞 不 好 会 影响 整个 项 目的 进程 。 




































































[ 消除 模糊 不 清 的 描述 】 

。 表述 同一 事物 时 统一 用 词 ， 使 表述 有 整体 感 

e “OO 等 "”“OO 左 右 ” 等 描述 要 列 出 所 有 可 能 性 一 例如 A.OO、B. 口 口 、C. AA 

e 能 数值 化 、 符 号 化 的 就 不 用 文字 描述 一 用 “>” d S <” 等 符号 以 及 具体 数值 替换 
文字 描述 

。 注 明 数 值 增 减 的 幅度 和 上 下 限 








© 明确 区 分 最 新 版 本 和 非 最 新 版 本 
存在 多 个 同名 ( 近似 名 称 ) 文档 会 市 来 混乱 。 相 信 很 多 人 见 过 下 面 这 种 文件 名 。 





。O 〇 OOO 修 正版 
。O 〇 OOO 最 终 版 
e 新 OOOO 
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这 些 文档 的 描述 往往 大 同 小 异 ， 却 都 各 目 存 在 一 些 需 要 修正 或 需要 更 新 的 地 方 。 要 解决 这 
个 现象 ， 最 好 是 对 所 有 同类 文件 的 描述 进行 一 个 汇总 ， 做 成 一 个 最 新 的 文档 ， 其 他 的 则 都 视 为 
日 文档 全 部 处 理 掉 。 

首先 把 可 以 确定 的 旧版 本 文 梢 删除 。 接 下 来 把 重复 的 文档 汇总 ， 选 出 其 中 更 新 日 期 最 近 、 
名 字 最 相似 的 两 个 进行 比 对 ， 详 细 记 录 二 者 的 区 别 ， 在 其 中 一 个 文件 中 进行 勤 误 及 汇总 。 汇 总 
完成 后 找 出 下 一 个 最 相近 的 文档 重复 上 述 工作 。 所 有 重复 文档 的 对 比 、 汇 总 完成 之 后 ， 将 用 作 
比较 对 和 象 的 文档 全 部 归档 到 一 起 ， 按 照 陈旧 文档 处 理 。 一 定 要 明确 区 分 最 新 版 本 和 旧版 本 的 保 
存 位 置 ， 防 止 再 发 生 相 同情 次。 像 管 理 源码 一 样 用 版 本 控制 系统 来 管理 文档 也 是 个 不 错 的 选择 。 

从 防止 同样 情况 再 次 发 生 的 角度 讲 ， 如 采 陈 旧 文 档 已 经 明确 失去 了 使 用 价值 ， 可 以 考虑 下 
接 删 除 。 














【 保持 文档 处 于 最 新 状态 】 

。 删除 确实 陈旧 的 文档 

e 根据 更 新 日 期 和 标题 选择 相近 的 文档 逐一 站 总 

。 做 出 最 新 版 本 的 文档 之 后 ， 其 余 文 档 全 部 视 为 陈旧 文档 处 理 
。 确认 没有 问题 的 情况 下 删除 陈旧 文档 














如 果 各 个 文档 的 审查 工作 正常 进行 ， 则 能 给 后 续 阶 段 砚 定 可 徘 的 基石 ， 你 证 在 过 到 问题 时 
有 据 可 依 。 希望 各 位 在 开始 编写 代码 之 前 和 完 腾 出 一 部 分 时 间 人 处 理 文档 ， 它 能 让 后 续 的 时 间 安 排 
更 加 灵活 高 效 。 





13.2.2 ”测试 设计 的 编写 方法 ( 输入 与 输出 ) 

测试 设计 的 编写 完成 时 间 最 晚 不 能 晚 于 功能 的 实现 。 

进行 测试 设计 时 ， 需 要 根据 测试 内 容 和 目的 不 同 编写 不 同 的 输入 文档 。 这 是 为 了 对 程序 进 
行 多 角度 测试 ， 从 而 尽量 减少 程序 存在 的 缺陷 。 








测试 测试 内 容 / 目的 

系统 测试 ( 又 称 综 合 测试 ) 最 终 成 品 严 格 按照 需求 运行 
性 能 测试 、 压 力 测试 ( 又 称 负 和 荷 测试 ) 使 用 者 使 用 时 感觉 不 到 压力 
集成 测试 ( 内 部 集成 / 外 部 集成 ) 各 功能 之 间 是 否 正 贡 协作 
详细 设计 UT 或 单元 测试 当前 功能 是 否 严格 符合 要 来 


( 实现 ) ( 试 运行 ) 功能 是 否 如 开发 者 预期 正常 实现 


























这 个 时 候 ， 要 注意 测试 设计 的 编写 是 


个 顺利 。 因 为 测试 的 实施 项 目 要 以 各 文档 内 记录 的 内 
容 以 及 正 第 状态 为 依据 来 编写 ， 所 以 这 一 过 程 中 能 明显 看 出 文档 的 好 坏 。 测 试 设计 的 编写 轻松 
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且 顺 利 ， 证 明文 档 质量 高 ， 反 过 来 如 果 编 写 测试 设计 时 频频 直到 难题 ， 则 说 明文 档 不 合格 。 要 
是 文档 中 多 处 出 现 13.2.1 市 提 及 的 问题 ， 最 好 重新 审查 一 融 文 档 。 
编写 测试 设计 时 常 出 现 的 问题 有 以 下 儿 个 。 





【问题 ) 

。 不 知 该 写 什么 ， 写 多 少 

。 测 试 设计 的 时 间 不 够 用 

。 文 档 记录 的 内 容 有 问题 

。 没 有 可 用 作 依据 的 输入 文档 








如 采 问 题 出 在 文档 目 刁 ， 那 么 只 需要 像 上 面 所 说 的 那样 ， 在 开始 编写 测试 设计 之 前 重新 碍 
看 并 审查 文 梢 即 可 解决 问题 。 就 算 没 有 充足 时 间 ， 也 尽量 不 要 在 没 更 新 文档 的 情况 下 和 二 接 根 据 
最 新 状态 编写 测试 设计 。 因 为 这 样 一 来 我 们 就 失去 了 客观 说 明 测试 设计 的 依据 。 更 新 文档 可 以 
让 所 有 相关 人 员 及 时 共 至 最 新 信息 ， 因 此 干 万 食 慢 不 得 。 

接 下 来 我 们 逐个 解决 剩 下 的 问题 。 








@ 明确 测试 的 目的 

如 果 测 试 的 项 目 只 求 详 细 ， 那 想 写 多 少 项 目 都 能 写 出 来 ( 当然 也 因 文 档 而 异 )。 同样 ， 项 目 
想 删 怎么 都 能 删 掉 。 所 以 在 设计 测试 时 要 注意 “必须 保证 的 点 (= 测试 的 目的 六 ， 区 分 重要 的 
项 目 和 不 重要 的 项 目 。 

测试 设计 既 要 完成 其 在 所 属 流程 内 应 当 完 成 的 所 有 任务 ， 又 不 能 重复 记录 属于 其 前 后 流程 
的 项 目 。 一 定 要 清楚 自己 编写 的 测试 设计 所 负责 的 阶段 以 及 需要 完成 的 任务 。 

另外 ， 对 于 用 文字 难以 表述 的 测试 设计 ， 用 另 附 表格 的 方式 往往 能 轻松 地 表述 清楚 。 需 要 
记录 多 种 情况 时 ， 可 以 在 测试 设计 文本 中 写 操作 流程 ， 然 后 男 附 表格 来 说 明 各 个 情况 ， 这 样 既 
可 以 让 文档 看 起 来 干净 利索 ， 又 能 有 效 防止 遗漏 。 总 而 言 之 ， 就 是 不 要 拘泥 于 定式 ， 选 择 最 符 
合 该 项 目测 试 的 形式 来 编写 测试 设计 。 

还 有 ， 一 个 项 目 内 要 确认 的 内 容 必 须 限制 在 一 个 。 比 如 在 “点 击 按钮 后 信息 写 入 数据 库 ” 
中 ,“ 生 成 报告 ”和 “各 项 目的 保存 内 容 正 确 无 误 ” 就 要 分 开 来 写 。 这 样 ， 在 实施 时 能 更 轻松 地 
判断 是 OK 还 是 NG。 









































【 写 什么 ， 写 多 少 】 

。 注意 该 测试 内 必须 保证 的 点 (= 测试 的 目的 )， 区 分 主干 和 枝叶 
。 不 写 属于 其 他 测试 中 要 保证 的 项 目 (防止 重复 ) 

e 难以 用 文字 表述 的 万 附 表 格 

。 一 个 项 目 内 需 确 认 的 内 容 限制 在 一 个 
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€ 从 重要 的 部 分 开始 与 

测试 设计 是 基于 文档 的 ， 那 么 一 旦 文档 编写 的 进度 洲 后 ， 势 必 会 压缩 测试 设计 的 时 间 。 很 
多 时 候 ， 留 给 测试 设计 的 日 程 安排 都 是 非常 紧 的 。 

这 里 重点 需要 注 蕊 的 地 方 和 上 面 有 些 类 似 ， 也 就 是 “ 写 什 么 ”“ 写 多 少 ”“ 能 不 能 不 写 ” 的 
问题 。 越 是 时 间 紧 的 时 候 ， 越 需要 仔细 阅读 文档 ， 然 后 从 草 要 的 部 分 开始 写 测 试 设 计 。 如 末 动 
手 之 前 不 先 谈 一 壳 ， 写 到 一 半 上 朋 定 会 直到 浇 贷 。 因 为 我 们 和 完 号 了 重要 的 部 分 ， 所 以 最 后 就 算 时 
间 不 够 用 了 ， 我 们 也 能 保证 重要 的 部 分 不 出 问题 。 如 来 真 的 完全 没有 时 间 可 用 ， 人 至 少 也 要 把 需 
要 检查 的 观点 和 方针 逐条 记录 下 来 ， 这 必然 会 对 实施 阶段 有 所 帮助 。 





























[ 时 间 不 够 用 的 时 候 ] 

e 仔细 阅读 文档 

。 从 重要 的 部 分 开始 写 

e 就 算 没 时 间 做 测试 设计 ， 也 要 将 观点 和 方针 逐条 记录 下 来 





@ 利用 所 有 可 以 利用 的 资源 

在 规模 较 小 或 人 数 较 少 的 开发 现场 ， 不 编写 文档 、 文 档 写 出 来 不 更 新 导致 形同虚设 的 情况 
时 有 发 生 。 

在 这 种 情况 下 ， 我 们 需要 一 边 回 相关 负责 人 咨询 所 需 信息 一 边 推 进 测试 设计 。 如 果 此 时 已 
经 有 了 能 够 揭 强 运行 的 程序 ， 最 好 一 并 拿 来 作 参 考 。 咨 询 来 的 信息 一 定 要 记录 下 来 ， 哪 人 只 是 
草草 作 个 笔记 也 好 ， 这 些 可 以 共享 的 资料 在 后 续 阶 段 必 然 会 用 得 到 。 每 次 咨询 之 后 都 要 做 个 总 
结 ， 这 能 避免 我 们 为 了 同一 件 事 反复 去 询问 负责 人 。 

在 没有 文档 可 用 的 情况 下 ， 如 果 能 认真 地 编写 测试 设计 ， 测 试 设 计 将 成 为 最 后 进行 规格 核 
对 时 的 重要 资料 。 

















[ 没有 文档 的 时 候 ] 

e JOB ETHER Y. SEEK SUB DL 
。 X A ARAWAKA vi 

e 把 咨询 到 的 信息 记录 下 来 ， 汇 总 保存 
。 要 比 有 文档 时 更 用 心地 编写 测试 设计 











总 而 言 之 ， 编 写 测试 设计 时 要 注意 我 们 上 面 提 到 的 所 有 问题 ， 同 时 综合 考量 程序 的 健壮 性 、 
发 布 前 的 日 程 安 排 等 因 叉 ， 在 此 基础 上 选择 与 测试 各 阶段 方针 相符 的 粒度 ， 根 据 所 选 粒 度 最 终 
完成 测试 设计 的 编写 。 

还 有 ， 由 于 需求 变更 时 必须 同时 修改 测试 设计 ， 所 以 测试 设计 要 尽量 选用 方便 添加 、 删 除 
操作 的 格式 ， 人 免得 修改 时 过 到 麻烦 。 
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13.2.3 测试 的 实施 与 测试 阶段 的 轮换 ( 做 什么 ， 做 多 少 ) 

本 部 分 所 讲 的 问题 通常 出 现在 正式 开始 测试 的 时 候 。 实 施 测 试 时 需要 同时 准备 相关 文档 以 
及 测试 设计 。 

开始 实际 测试 程序 时 常 出 现 的 问题 有 下 面 几 个 。 





【 问题 】 

。 没 时 间 实 施 所 有 测试 

e Bug 太 多 ， 测 试 难以 进行 

。 不 清楚 在 发 现 Bug 时 如 何 报告 
。 没有 测试 设计 





下 面 我 们 来 对 这 些 问题 进行 逐条 改善 。 


@ 实施 测试 时 也 要 有 优先 顺序 

有 些 时 候 ， 我 们 不 缺 文 档 和 测试 设计 ， 但 交付 期 前 紧迫 的 时 间 让 我 们 无 法 完成 数量 庞大 的 
全 部 测试 项 目 。 从 整个 项 目的 优先 顺序 来 讲 ， 人 们 往往 会 先 照 顾 交 付 期 ， 把 执行 全 部 测试 项 目 
放 到 其 次 。 遇 到 这 种 情况 我 们 应 该 怎么 办 呢 ? 

首先 ， 要 确认 交付 期 是 否 真 的 无 法 延 后 。 缩 短 测 试 期 意味 着 可 以 保证 的 项 目 相应 减少 ， 这 
很 有 可 能 导致 发 布 后 出 现 Bug 和 安全 问题 ， 直 接 影响 信誉 。 

我 们 需要 从 整个 项 目的 角度 出 发 ,重新 认真 衡量 一 下 得 失 ， 确 认 交 付 期 是 否 真 的 优先 于 上 
述 几 点 。 

如 果 考 虑 到 项 目 整 体 平衡 而 需要 删除 某 些 测试 项 目 ， 那么 在 选择 项 目前 最 好 先 按 照 以 下 条 
件 对 测试 项 目 进行 梳理 及 分 类 。 














e 已 经 完成 的 / 尚未 完成 的 
。 PÉRIR A / 束 算 没完 成 也 可 以 删除 而 不 影响 发 布 的 
。 必须 详细 进行 测试 的 /大 概 确认 一 下 就 可 以 的 


以 上 述 分 类 标准 为 参考 ， 给 各 项 目 设置 优先 顺序 如 下 。 


e FRA: 已 经 实现 ， 且 不 完成 就 无 法 发 布 的 功能 
e FRB: 尚未 实现 ， 但 不 完成 就 无 法 发 布 的 功能 
e 等 级 C: 大 概 确认 一 下 就 可 以 的 /实在 不 行 删 挥 也 可 以 的 功能 





A 和 B 是 发 布 所 需 的 最 低 限 度 的 功能 ， 因 此 如 采 它 们 的 测试 不 够 充分 ， 我 们 连 最 低 限 度 的 
功能 部 无 法 保证 。 这 两 类 项 目的 测试 时 间 一 旦 无 法 保证 ， 必 须 同 交付 方 进行 交涉 。 
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如 来 无 论 如 何 都 无 法 延期 ， 则 需要 将 测试 能 细 分 的 细 分 ， 不 能 细 分 的 调整 粒度 (= Hh] MR 
证 范围 ， 浴 加 限制 。 此 时 需要 保证 整个 团队 达成 共识 )。 

C 部 分 就 是 与 时 间 赛 跑 ， 先 把 这 些 测 试 按 优先 级 排 成 一 条 线 ， 然 后 逐个 实施 。 这 里 要 做 好 
心理 准备 ， 因 为 排 在 后 半 部 分 的 项 目 多 数 时 候 没 时 间 实 施 。 

确定 优先 顺序 时 要 避免 模糊 不 消 的 等 级 制 ， 一 定 要 严格 排序 。 这 是 为 了 保证 那些 必 不 可 少 
的 测试 能 够 先 执行 完 。 这 里 一 旦 用 了 模糊 不 清 的 等 级 制 ， 等 到 火烧 眉毛 的 时 候 往往 会 出 现 “ 全 
都 是 A” 的 情况 ,或 者 冒 出 来 “AA 级 ”“S 级 ”之 类 原先 根本 不 存在 的 等 级 。 这 就 使 当初 的 分 
级 失去 了 音义。 确定 优先 顺序 是 为 了 给 测试 项 目 划 分 界限 (这 里 界限 的 标准 不 是 “哪些 知 要 保 
证 ”， 而 是 “哪些 可 以 不 用 保证 ”)， 以 备 万 不 得 已 之 时 可 以 将 没 必要 的 东西 砍 反 ， 因 此 决 不 能 
半点 模糊 。 

制定 方针 、 共 孚 方针 之 后 ， 剩 下 的 就 是 跟 时 间 赛 跑 ， 在 剩余 时 间 内 做 到 最 好 了 。 

关于 优先 顺序 再 补充 一 点 ， 性 能 、 压 力 测 试 等 非 功 能 测试 要 在 环境 具备 一 定 条 件 时 尽早 实 
施 。 因 为 如 果 拖 到 一 部 分 功能 完成 后 再 做 ， 出 现 问题 时 需要 排查 的 范围 将 会 很 大 ， 修 正 /重新 
测试 的 周期 也 会 很 长 。 

为 外 ， 这 些 测试 要 在 测试 实施 的 各 阶段 定期 进行 。 这 听 起 来 虽然 与 前 面 的 言论 日 相 了 矛盾 ， 
但 要 知 直 ， 非 功能 需求 和 功能 需求 一 样 ， 有 些 问题 只 有 在 集成 之 后 才 会 显现 出 来 。 



































【时间 不 够 用 的 时 候 ] 

。 确认 是 否 真 的 无 法 延期 

e 确定 优先 顺序 ， 先 测试 必 不 可 少 的 项 目 

。 优先 级 较 低 的 项 目 排 成 一 条 下 线 逐 个 执行 (万 不 得 已 时 和 丰 接 放弃 ) 
。 非 功能 需求 的 测试 要 尽早 地 、 持 续 地 实施 














€ 问题 过 多 时 先 着 眼 大 局 

有 时 我 们 会 遇 到 这 种 情况 : 开始 测试 之 后 ， 程 序 到 处 都 是 毛病 根本 无 法 运行 ， 或 者 按 日 程 
表 来 说 理应 完成 的 功能 却 不 能 用 ， 结 末 导 致 安排 好 的 测试 项 目 无 法 推进 。 这 种 时 候 就 要 暂时 放 
下 测试 ， 先 把 已 经 完成 的 功能 和 未 完成 的 功能 分 个 类 ， 做 成 清单 共 至 给 团队 。 

实现 阶段 的 进度 一 旦 与 认 知 出 现 偏差 ， 很 可 能 发 展 成 影响 整个 项 目 进 度 的 问题 ， 因 此 需要 
尽早 做 到 信息 共 圣 。 如 果 功 能 已 经 实现 , 但 是 品质 方面 存在 问题 ， 则 党 要 确定 问题 的 优先 顺序 
并 逐个 检查 。 出 现 问 题 时 眼光 不 能 局 限 在 一 个 功能 内 ， 要 尽量 站 在 全 局 角度 。 





D 安全 方面 的 问题 
Q 功能 是 否 正常 运行 
O 数据 的 显示 、 读 写 是 否 正常 
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由 设计 方面 的 问题 


测试 时 ， 先 像 上 面 这 样 大 致 列 出 几 个 重点 ， 把 当前 功能 中 优先 级 高 的 项 目测 试 完 ， 然 后 暂 
时 跳 过 优先 级 低 的 项 目 ， 百 接 开 始 下 一 个 功能 的 测试 。 等 到 所 有 优先 级 高 的 项 目测 试 完 后 ， 再 
回 过 头 来 逐个 解决 优先 级 低 的 项 目 。 


【缺陷 过 多 的 时 候 ] 

。 区 分 有 缺陷 的 功能 和 未 实现 的 功能 ， 将 未 实现 的 部 分 做 成 清单 共 至 出 来 
。 给 要 实施 的 测试 项 目 制定 优先 顺序 

e 日 光 不 局 限 在 一 个 功能 内 ,测试 尽量 照顾 到 整体 














e 缺陷 报告 要 简洁 、 详 细 
如 果 在 测试 过 程 中 发 现 缺陷 ， 应 该 如 何 报告 呢 ? 如 果 只 说 “无 法 运行 ”“ 运 行 不 正常 ”， 
责 修改 的 人 也 无 从 改 起 。 所 以 要 尽量 加 入 一 些 详细 信息 。 





zs 





e 实施 时 间 
。 实施 环境 
e 实施 者 〈 负责 实施 的 人 ， 或 者 当时 登录 系统 的 用 户 等 ) 
。 实 施 意 图 


e 出 现 的 问题 (与 预想 结果 的 仿 差 ) 











些 都 是 在 重 现 问题 或 者 检查 问题 现状 时 必 不 可 少 的 信息 。 将 实施 时 间 加 入 报告 是 为 了 让 
人 能 通过 程序 日 志 进 行 调查 。 因 为 有 些 问 题 只 有 在 特定 时 间 才 会 发 生 。 
报告 里 还 要 尽量 留 下 证 据 。 另 外 ， 执 行 测 试 时 的 输入 值 、 执 行 前 后 数据 库 的 状态 最 好 也 保 
来 。 这 些 能 在 发 生 问 题 时 大 幅 减 轻 调 查 的 压力 。 能 否 还 原 发 生 问 题 时 的 情况 ， 下 接 影 啊 着 
解决 问题 的 速度 。 

遇 到 那些 党 得 不 对 劲 ， 但 是 又 无 法 根据 文档 判断 是 否 为 缺陷 的 问题 时 ， 也 要 作出 报告 。 信 
助 整个 团队 的 力量 解决 问题 要 远 比 一 个 人 伤 脑筋 来 得 快 。 另 外 需要 注意 ， 出 现 这 种 难以 判断 的 
情况 时 ， 意 味 看 设计 阶段 很 可 能 潜 减 了 大 问题 。 























【 发 现 缺 陷 的 时 候 】 

o i 

。 尺 可 能 地 留 下 证 据 

ww ENERES TN REA 
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@ 即便 没有 测试 设计 ， 也 要 保证 方针 共享 

根据 项 目 规 模 和 发 布 剖 的 日 程 安排 ,我 们 有 时 候 会 大 胆 放 莽 测试 设计 ， 或 者 由 于 时 间 太 紧 
没 能 完成 测试 设计 。 

学 习 测 试 设计 的 时 候 我 们 学 习 过 ， 当 剩余 时 间 真 的 不 够 用 的 时 候 ， 至 少 要 保证 观点 或 方针 
明确 。 在 此 基础 上 ， 再 根据 实施 时 的 优 和 顺序 ， 从 一 旦 发 生 缺 陷 可 能 引发 严重 问题 的 地 方 开始 
测试 。 如 末 开 始 测 试 后 才 发 现 问 题 比 想象 中 复杂 ， 难 以 解决 ， 至 少 要 把 需 确 认 的 项 目 逐 条 记录 
F3. 




















[ 没有 测试 设计 的 时 候 ] 

e 确认 、 共 至 观点 和 方针 

e 优先 处 理 最 可 能 引发 问题 的 地 方 

e 对 于 太 过 复杂 难以 测试 的 地 方 ， 逐 条 列 出 需 确认 的 项 目 


由 于 实施 测试 的 阶段 位 于 整个 项 目的 后 半 部 分 ， 所 以 往往 需要 与 时 间 赛 跑 。 但 即便 时 间 不 
够 用 ， 我 们 也 要 有 计划 地 推进 测试 ， 力 求 提 高 效 靳 ， 用 最 少 的 天 力 换 来 最 大 的 效果 。 





13.3 小结 : 测试 并 不 可 怕 


本 章 我 们 讲 了 在 项 目 早期 阶段 导 和 人 测试 观点 能 市 来 的 几 点 改善 。 

说 得 笼统 一 点 ， 就 是 确定 一 个 正确 的 状态 ,检查 当前 状态 与 正确 状态 之 间 有 多 少 偏差 ， 然 
后 考虑 脏 样 做 能 修正 这 些 偏 差 。 人 至 于 思路 和 需 确 认 的 事项 等 ,很 多 都 可 以 下 接 拿 到 编程 的 过 程 
中 重复 利用 。 测 试 能 够 担保 的 东西 其 实 并 不 多 ， 充 其 量 不 过 是 在 有 限 的 范围 内 做 个 保证 ， 比 如 
“能 防止 这 类 错误 ”“ 这 种 情况 在 预料 之 中 ”等 ， 不 可 能 保证 完全 的 正确 性 。 测 试 能 够 证 明 “ 这 
个 缺陷 已 被 修复 ”， 却 不 能 证 明 “ 这 里 已 经 没有 缺陷 了 ”。 

男 外 ,设计 者 、 实 现 者 都 是 活生生 的 人 ,难免 犯错 和 下 忽 。 所 以 ,无论 我 们 在 开发 过 程 中 
多 么 译 慑 ， 也 不 可 能 将 出 现 问题 的 可 能 性 降 为 等 。 

测试 要 有 计划 性 。 无 计划 的 测试 不 但 浪费 时 间 ， 获 得 的 成 效 也 低 。 相 反 地 ， 有 计划 的 测试 
能 帮助 我 们 提高 程序 的 品质 。 由 于 往往 到 了 项 目 后 半期 ,测试 才 受 到 重视 ， 所 以 人 们 的 注意 力 
利 会 被 实现 代码 的 过 程 吸 引 ， 忘 记 去 关注 测试 。 但 是 我 们 和 希望 各 位 能 在 项 目的 初期 就 去 有 意识 
地 若 顾 测试 ， 放 开 胆 子 与 测试 携手 同行 ， 从 而 提高 开发 的 品质 。 





















































第 14 章 轻松 使 用 Django 


基于 Python 开发 的 Web 应 用 框架 有 很 多 ,例如 Pyramid, Flask, Bottle, Tornado 等 。 本 章 
我 们 将 目光 放 在 Django 上 ， 首 先 对 其 进行 徐 单 学 习 ， 然 后 了 解 一 些 在 实际 开发 过 程 中 对 Django 
有 辅助 作用 的 库 。 





14.1 Django 简介 


Django zé—3X3& F Python 开发 的 全 栈 式 一 体 化 Web 应 用 框架 。2003 年 问世 之 初 ， 它 只 是 
美国 一 家 报社 的 内 部 工具 ，2005 年 7 月 使 用 BSD 许可 证 完成 了 开源 。 其 目的 是 削减 代码 量 ， 简 
单 日 迅速 地 搭建 以 数据 库 为 主体 的 复杂 Web 站 点 。 它 是 全 栈 式 框 架 ， 因 此 安 朔 起 来 很 简单 ， 而 
日 使 用 者 众多 。 这 使 得 Django 除 具 有 完备 的 官方 文档 之 外 ， 还 有 大 量 的 关联 文档 、 丰 宦 的 第 三 
方 库 可 供 使 用 。 与 其 他 框架 相 比 ，Django 用 起 来 要 轻松 得 多 。 











14.1.1 Django 的 安装 
Django 的 安装 与 其 他 Python 程序 包 一 样 ， 需 要 通过 pip 进行 。 
$ pip rastall cy eno 


本 书 使 用 了 Django 的 1.7.1 版 。 


14.1.2 Django 的 架构 





Django 继承 并 简化 了 MVC 架构 。MVC 中 的 Controller 部 分 基本 全 由 Django 完成 。View 
部 分 则 被 分 割 为 两 部 分 ， 即 负责 HTML 泻 染 的 模板 和 负责 显示 逻辑 的 视 网 。 所 以 Django 又 被 
PKJ MTV ( Model-Template-View ) HEX, 3X Django HERRER f. MTV 框 染 的 核心 部 分 ， 即 O/R 
映射 工具 、URL Z4rHüizs( Dispatcher )、 视 图 、 模 板 系统 之 外 ， 还 有 管理 界面 、 绥 存 系统 、 国 际 
化 支持 、 表 单 处 理 等 机 制 和 功能 。 

使 用 Django 开发 Web 应 用 站 点 时 ， 需 准备 一 个 素 载 大 Django 实例 及 数据 库 设 置 等 内 容 的 
工程 ， 然 后 通过 在 该 工程 中 新 建 几 个 应 用 或 者 调用 外 部 应 用 ， 或 者 将 二 者 结合 起 来 进行 开发 。 
由 于 每 个 应 用 的 本 质 都 是 Python 程序 包 ， 所 以 只 要 按 功 能 ( 模型、 视图、 模板 等 ) 对 这 些 包 进 
行 分 离 ， 完 全 可 以 拿 到 其 他 工程 中 重复 利用 。 
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图 14.1 是 Django 架构 处 理 请 求 的 流程 。 


`E x 
请 求 " dE 


模板 系统 











URL Dieas 





管理 界面 






工程 设置 文件 ( memcached 等 ) 


用 于 工程 用 于 Django 
管理 的 脚本 管理 的 脚本 


14.1 Django 的 架构 


(D 客户 端 发 来 的 HITP 请 求 被 视 为 Django 的 请 求 对 象 





D URL 分 配 融 负 责 搜索 并 调用 被 请 求 的 URL 所 对 应 的 视图 
C) 被 调用 的 视图 视 情 况 使 用 模型 或 模板 生成 响应 对 象 
D 响应 对 象 作为 HTTP 响应 发 回 给 用 户 








接 下 来 我 们 按 顺 序 了 解 一 下 Django WRI o 


e 工程 

工程 是 承载 了 Django 实例 的 所 有 设置 的 Python 程序 包 。 大 部 分 情况 下 ， 一 个 Web 站 点 就 
是 一 个 工程 。 工 程 内 可 以 新 建 及 存放 该 工程 回 有 的 应 用 ， 或 者 保存 Web 站 点 的 设置 (数据库 设 
t. Django 的 选项 设置 、 各 应 用 的 设置 等 )。 

如 果 完 整 安 装 了 Django， 可 以 使 用 Django 管理 脚本 django-admin 的 startproject 命令 创建 
工程 目录 mypr 和 初始 文件 。 











$ django-admin startproject myprj 
myprj 的 布局 如 下 所 示 。 


myprj/ 
manage.py 
myprj 
Init ,JY 
settings.py 
UAS MOY 
wsgi.py 
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€ 应 用 
对 于 Django 而 言 ， 应 用 指 的 是 表示 单一 功能 的 Web 应 用 的 Python 程序 包 。 由 于 其 实质 就 
是 Python 程序 包 ， 因 此 放 在 PYTHONPATH 有 效 的 任何 位 置 都 没有 问题 。 这 里 最 好 尽量 减少 应 
用 与 工程 、 应 用 与 其 他 应 用 之 间 的 依赖 关系 ， 做 到 功能 独立 ， 以 便 在 其 他 工程 中 重复 利用 。 
比如 我 们 要 创建 名 为 polls 的 应 用 ， 就 可 以 使 用 刚刚 在 工程 目录 下 生成 的 工程 管理 脚本 


manage.py, 1AÍ] startapp fi. 











Seele qoas] 
$ python manage.py startapp polls 


随后 会 按照 下 列 布局 生成 polls 目录 及 初始 文件 。 





polls/ 
o imit ,BY 
admin. py 


migrations 


| imit -Y 


models .py 
tests.py 


views.py 


© 模型 

Django 提供 了 O/R 映射 工具 ， 因 此 可 以 用 Python 代码 来 描述 数据 库 布局 。 

每 个 模型 都 是 继承 了 django.db.models.Model 类 的 Python 的 类 ， 分 别 对 应 数据 库 中 的 一 个 
表格 。 通 过 将 数据 库 的 字段 、 关 系 、 行 为 定义 为 模型 类 的 属性 或 方法 ， 我们 可 以 使 用 丰 宇 且 灵 
活 的 数据 库 访 问 API。 








e URL 分 配器 

URL 分 配 需 机 制 使 得 URL 信息 不 再 受 框架 及 扩展 名 的 制约 ， 从 而 让 Web 应 用 的 URL 设计 
保持 简洁 。 

URL 在 URLconf 模 块 中 进行 描述 ，URLconf 模 块 中 包括 使 用 正则 表达 式 书写 的 URL 和 
Python 也 数 的 映 象 。URLconf 能够 以 应 用 为 单位 进行 分 割 ， 因 此 提高 了 应 用 的 可 重复 利用 性 。 
另外 ， 我 们 可 以 利用 给 URL 设置 名 称 并 定义 的 方式 让 代码 和 目标 直接 通过 该 名 称 调用 URL, 
从 而 将 URL 设计 与 代码 分 离 。 














@ 视图 
Django 的 视图 是 一 类 清 数 ， 它 能 够 生成 指定 页 面 的 HttpResponse 对 象 或 像 Http 404 这 样 的 
异常 情况 ， 返 回 HTTP 请 求 。 典 型 的 视图 因数 的 处 理 流程 通常 是 先 从 请 求 参数 中 获取 数据 ， 访 
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取 模 板 ， 然 后 根据 获取 到 的 数据 演 染 模板 。 


€ 模板 系统 

在 Django 的 概念 中 ， — 只 负责 显示 ， 并 不 是 编写 逻辑 代码 的 环境 。 因 此 Django HJ 
模板 系统 将 设计 与 内 容 、 代 码 分 离开 来 了 ， 是 一 种 功能 强 、 扩 展 性 高 、 对 设计 者 很 友好 的 模板 
语言 。 

模板 基于 文本 而 不 是 XML， 因 此 它 不 但 能 生成 XML 和 HTML， 还 能 生成 E-mail、 
JavaScript, CSV 等 任意 文本 格式 。 

男 外 ， 如 采 使 用 模板 继承 功能 ， 子 模板 只 需要 将 父 模 板 中 预 留 的 空位 填 满 即 可 。 我 们 在 编 
写 模板 时 只 需要 描述 各 个 模板 独 有 的 部 分 ， 因 此 可 以 省 去 重复 元 余 的 编码 过 程 。 











e 管理 界面 

大 多 Web 应 用 在 运行 过 程 中 ， 都 需要 一 个 专 供 拥有 管理 员 权限 的 用 户 添 加 、 编 辑 、 删 除数 
据 的 界面 ,但 是 实际 制作 这 个 界面 并 不 容易 。 

Django 只 需 将 已 完工 的 模型 添加 到 管理 站 点 ， 就 能 根据 模型 定义 动态 地 生成 面 ， 为 我 们 提 
供 一 个 功能 齐全 的 管理 界面 (图 14.2、 图 14.3) 








Django 管理 欢迎 ADMIN. 查看 站 点 / 修改 密码 / 注销 


Recent actions 








图 14.2 ”登录 管理 界面 后 的 首页 





Django 管理 
首页 ; Polls ; Polls» h0 poll 
增加 poll 
Question text: 你 喜欢 哪 种 编程 语言 ? 9 十 月 2014 e 
M T W I F S S 
Date published: BH : XXE 4 c2 3 4 s 
时 间 现在 1O 8 
15 
22 25 26 
28 29 30 31 
Ey 








图 14.3 ”管理 界面 的 模型 编辑 界面 
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e 缓存 系统 

Django 可 以 使 用 memcached 等 缓存 后 端 ( Cache Backend ) 轻松 地 缓存 数据 。 比 如 可 以 将 动 
态 页 面 的 泻 染 结 采 (部 分 或 全 部 ) 缓存 下 来 ， 等 到 下 次 需要 时 有 直接 谈 取 缓存， 从 而 不 必 每 次 都 
对 动态 页 面 进行 处 理 。 

绥 存 的 后 端 可 以 从 memcached、 数 据 库 、 文 件 系统 、 本 地 内 存 等 位 置 中 进行 选择 。 缓 存 对 
象 也 文 持 整个 网 站 、 特 定 的 整个 视图 、 部 分 模板 、 特 定数 据 等 。 

















14.1.8 Django 的 文档 


在 下 述 网 站 上 可 以 阅览 Django 1.7 ~ 1.10 以 及 dev 版 的 英文 文档 。 





Django documentation 








https://docs.djangoproject.com/ 





从 下 一 节 开 始 ， 本 章 的 内 容 均 面 加 有 Django 使 用 经 验 的 读者 ， 因 此 ， 在 进入 下 一 市 的 学 习 
之 前 ,请 先 阅 读 文 档 内 的 教程 部 分 。 





Django 教程 
https://docs.djangoproject.com/en/1.7/intro/tutorial01/ 











14.2 ”数据 库 的 迁移 


14.2.1 什么 是 数据 库 的 迁移 


数据 库 的 迁移 ( Migration ) 是 对 数据 库 中 的 模式 定义 以 及 数据 转移 进行 定理 的 功能 。 它 的 
主要 作用 是 版 本 管理 以 及 版 本 升级 、 回 深 等 ， 类 似 于 Ruby 的 Ruby on Rails HEX, 

那么 ,在 什么 场合 下 才能 体会 到 它 的 便捷 之 处 呢 ? 我 们 经 过 亲 二 实践 ， 认 为 它 在 以 下 场合 
能 发 挥 极 大 作用 。 








@ 多 人 持续 开发 时 
多 人 共同 开发 的 时 候 ， 应 用 程序 经 常 要 反映 别人 的 修改 ， 所 以 模式 升级 和 回 深 的 机 会 也 相 


对 较 多 。 
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€ 需要 在 运行 过 程 中 修改 数据 表 时 
如 有 果 需 要 在 运行 过 程 中 修改 数据 表 ， 束 必须 修改 模式 以 防止 现 有 数据 受 损 。 为 外 ， 一旦 修 
改 后 出 现 问 题 ， 还 需要 立刻 进行 恢复 。 这 种 时 候 就 必须 做 好 版 本 管理 ,保证 随时 可 以 回 深 。 


14.2.2 Django 的 迁移 功能 


@ Django 数据 库 迁 移 

Django 的 迁移 功能 文 持 给 模型 瀛 加 新 的 字段 、 癌 数据 库 的 列 瀛 加 null=Ture 等 。 在 版 本 管理 
方面 ，Django 以 模型 为 基准 ， 通 过 生成 并 执行 迁移 文件 来 完成 数据 库 版 本 的 更 新 ， 从 而 实现 版 
本 管理 。 

迁移 文件 同时 也 是 从 零 新 建 数据 库 的 方法 之 一 。 第 一 个 迁移 文件 的 执行 结果 是 从 空 模 式 迁 
移 为 初始 状态 的 数据 表 。 等 到 所 有 迁移 文件 执行 完毕 之 后 ， 我 们 就 会 得 到 应 用 了 最 新 版 本 的 数 
据 库 模 式 。 男 外 ， 如 果 有 上 一 个 版 本 的 数据 库 ， 那 么 只 需 执 行 最 后 生成 的 迁移 文件 即 可 得 到 最 
新 的 数据 库 模式 。 














@ 示例 ( 对 新 建 的 应 用 套用 迁移 时 ) 
接 下 来 我 们 以 新 建 应 用 的 情况 为 例 来 学 习 一 下 迁移 功能 。 首 先 新 建 一 个 应 用 ( LIST 14.1 )。 


© LIST 14.1 新 建 polls 应 用 


$ python manage.py startapp polls 





新 建 polls 应 用 之 后 ， 首 先 在 settings.py 的 INSTALLED APPS 中 添加 polls， 然 后 在 polls/ 
models.py 中 创建 模型 ( LIST 14.2 )。 











© LIST 14.2 myprj/settings.py 


INSTALLED APPS - ( 


Herode 





polls 应 用 需要 投票 项 目 ( poll ) 和 选项 ( choice ) 两 个 模型 ， 这 里 我 们 只 创建 poll。poll 中 要 
包含 题目 ( question test ) 的 信息 (LIST 14.3 )。 


© LIST 14.3 polls/models.py 
4 -*- coding: utf-8 -*- 


from django.db import models 
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class Poll (models .Model): 
question text = models.CharField (max length=200) 


接 下 来 要 做 的 是 生成 迁移 文件 。 迁 移 文 件 通 过 makemigrations 命令 生成 (LIST 14.4 )。 


B LIST 14.4 生成 第 一 个 迁移 文件 


$ python manage.py makemigrations polls 
Migraciones cor o 
000l initial py: 
- Create model Poll 


执行 上 述 命令 后 ， - polls/migrations/0001 initial.py 迁移 文件 。 此 时 数据 库 中 还 没有 
polls, 2 这 里 我 们 需要 通过 migrate 命令 执行 迁移 文件 ， 从 而 生成 polls(LIST 14.5 )。 


© LIST 14.5 ”执行 migrate 


$ python manage.py migrate 
Operations to perform: 

Apply all migrations: admin, contenttypes, polls, auth, sessions 
Running migrations: 

Applying contcenttypes. 0001 du d s» OK 

Applying auveEn,000l initial,.. OK 

Applying ecmin. O00l 1ialtial,,. OK 

Applying polle. 0001 _ imitial..» OK 

Zool en sessons AMOCO O 


此 时 会 发 现 poll 还 缺少 公布 日 期 ( Publication Date )， 于 是 我 们 还 需要 为 它 添 加 公布 日 期 
(LIST 14.6 )。 


© LIST 14.6 polls/models.py 


4 -*- coding: utf-8 -*- 


from django.db import models 


class Poll(models.Model): 
cquestiom text Sedes sebbene 209) 
# 添加 公布 日 期 
pulo Carce = moCels. Dal epee carce us ee 


此 类 细微 修改 也 能 通过 迁移 功能 完成 。 做 修改 时 也 要 用 makemigrations 命令 生成 迁移 
文件 ( LIST 14.7 )。 


© LIST 14.7 ”生成 用 于 修改 的 迁移 文件 


$ python manage.py makemigrations polls 
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You are trying tO ace a non-mulleable fiele) (pub date! to Ol without Qs 
we can't do that (the database needs something to populate existing rows). d 
Please select a fix: 

1) Provide a one-off default now (will be set on all existing rows) 


2) Quit, and let me add a default in models .py 


此 时 ， 计 算 机 表示 “pub date 中 没有 设置 default”， 询 问 如 何 处 理 已 有 数据 。 选 择 1 可 以 回 
已 有 数据 输入 要 设置 的 但 ， 选 择 2 则 可 以 中 上 断 迁 移 文件 的 生成 。 这 里 我 们 选择 1。 计 算 机 告诉 
我 们 可 以 使 用 datetime module 和 Django 的 timezone mudule， 这 里 我 们 选择 timezone .now () 
《有 时 区 概念 的 当前 时 间 。 回 数据库 中 添加 的 值 为 UTC ) ( LIST 14.8 )。 


© LIST 14.8 设置 default 数据 


Select an option: 1 
Please enter the default value now, as valid Python 
The datetime and django.utils.timezone modules are available, so you can do e.g. 
timezone.now() 4 
>>> timezone.now() 
Migrations for 'polls': 

0002 Boll pulo carte. p. 

=- ACC Fleld pulo date To POLN 


到 此 ， 用 于 修改 的 迁移 文件 生成 完毕 。 只 生成 迁移 文件 并 不 能 将 修改 反映 到 数据 库 中 ， 因 
此 别 忘 了 执行 migrate(LIST 14.9 )。 


回 LIST 14.9 执行 migrate 


$ python manage.py migrate 
Operations to perform: 

Apply all migrations: admin, contenttypes, polls, auth, sessions 
Running migrations: 


Applying Polls. 0002 poll puo Cate. OK 


这 样 一 来 ， 修 改 就 反映 到 数据 库 中 了 。 
以 上 就 是 迁移 的 苛 本 使 用 方法 。 只 要 记 住 makemigrations 和 migrate AMAMA, WÈ 
能 够 应 付 绝 大 部 分 情况 。 不 过 例外 总 还 是 有 的 ， 为 此 我 们 来 简单 了 解 一 下 各 个 命令 。 





O migrate 
用 于 执行 迁移 文件 的 命令 (LIST 14.10, LIST 14.11 )。 
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© LIST 14.10 指定 应 用 执行 


$ python manage.py migrate application 


加 LIST 14.11 指定 文件 名 或 编号 执行 


$ python manage.py migrate application file name or number 


该 命令 可 以 指定 应 用 或 文件 名 来 执行 。 如 来 不 指定 ， 则 会 执行 所 有 应 用 尚未 执行 过 的 迁移 
par 


e --fake 
该 选项 可 以 将 未 执行 的 迁移 文件 标记 为 已 执行 ， 但 不 实际 执行 该 文件 。 比 如 存在 编写 很 
卓 的 未 执行 的 迁移 文件 ， 但 当前 的 数据 库 状态 下 执行 该 文件 会 出 现 错 误 时 ， 就 可 以 使 用 


这 个 选项 。 





O makemigrations 


用 于 生成 迁移 文件 的 命令 。 


e --empty 
用 于 生成 空 迁移 文件 的 选项 。 在 我 们 想 手动 编写 迁移 文件 的 内 容 ， 或 者 需要 生成 用 于 数 
据 迁 移 的 文件 时 ， 可 以 使 用 该 选项 。 关 于 数据 迁移 的 详细 内 容 ， 我 们 将 在 “数据 迁移 ” 


部 分 学 习 。 


O sqlmigrate 
该 命令 可 以 查看 套用 迁移 文件 时 执行 的 SQL(LIST 14.12 )。 


E LIST 14.12 ”查看 执行 的 SQL 


$ python manage.py sqlmigrate application file name or number 


e 数据 迁移 

学 习 makemigrations 的 --empty 选项 时 我 们 了 解 到 ，Django 可 以 借助 迁移 功能 做 数据 迁 
移 。 数 据 迁 移 是 伴随 着 值 的 变化 的 数据 库 模式 变更 ， 为 与 一 般 的 模式 迁移 作 区 分 ， 才 被 称 为 数据 
迁移 。 下 面 我 们 试 着 做 一 个 让 poll 的 公布 日 期 延 后 一 天 的 数据 迁移 (LIST 14.13、LIST 14.14 )。 








© LIST 14.13 ”生成 用 于 数据 迁移 的 文件 


$ python manage.py makemigrations --empty polls 
Migrations for 'polls': 


0003 auto 20141104 0236.py: 
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© LIST 14.14 0003_auto_20141104_0236.py 


4 -*- coding: utf-8 -*- 


trom bc import unicode literale 

from django.db import models, migrations 

class Migration (migrations.Migration): 
dependencies = [ 


("polle', 10002 poll pub carce!) ， 


operations = [ 


] 


生成 的 迁移 文件 中 只 有 类 的 定义 和 空 的 方法 ， 并 没有 描述 实际 的 处 理 。 我 们 只 需 添加 数据 
迁移 所 需 的 处 理 ， 即 可 用 它 来 做 数据 迁移 (LIST 14.15 )。 





© LIST 14.15 添加 让 公布 日 期 延 后 一 天 的 数据 迁移 
# -*- coding: utf-8 -*- 
"sewn c em ee ns 


import datetime 


from django.db import models, migrations 


denirorvacdipubkdateiboy enema pps seem cs 
POLL = &pps- get model ('polls", "BOLL" ) 
Tor POLL ima PoLL.- objects ALL) s 
POLL. pub carte += datetime, timedelta das 


poll.save() 


cer backward pulo Cate by one day a Schema eclLtor) < 
POLL = @pps- -get model edd s Dep 
or POLL ia POLL. objects. aLL) s 
poLL. pub cate -= datetime., timedelta c 


poll.save() 


class Migration (migrations.Migration): 


dependencies = [ 


('polls', '0002 poll pub date'), 
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operations = [ 
mieegtrxomssunbycHuom0oboswasdspubsEdatesbysoneuwdaoys 
backward pub date by _ one qdqay) 
] 


添加 完 处 理 之 后 ， 执 行 migrate， 将 其 反映 到 数据 库 中 (LIST 14.16 )。 


回 LIST 14.16 ”执行 migrate 


$ python manage.py migrate 
Operations to perform: 

Apply all migrations: admin, contenttypes, polls, auth, sessions 
Running migrations: 


Applying polls.0003 auto 20141104 0236... OK 
想 了 解数 据 迁移 的 更 多 内 容 可 以 参考 Django 的 迁移 文档 ^. 


€ 迁移 文件 的 squash 

随 厦 迁移 的 频 蚂 使 用 ， 迁 移 文 件 会 越 积 越 多 ， 执 行 时 间 目 然 越 来 越 长。 如 末 想 缩短 时 间 ， 
就 需要 将 多 个 迁移 文件 合并 成 一 个 ， 这 时 可 以 使 用 squashmigrations 命令 (LIST 14.17 )。 
比如 在 发 布 Web 应 用 时 将 所 有 迁移 文件 合并 成 一 个 ， 这 样 一 来 我 们 在 搭建 环境 时 就 只 需要 执行 


= 





回 LIST 14.17 迁移 文件 的 squash 


$ python manage.py squashmigrations polls 0003 
Will squash the following migrations: 

= 0001 1imnmitial 

= 0002 _ poll pub carce 

- 0003 auto 20141104 0236 


Do you wish to proceed? [yN] 





计算 机 询问 是 否 执行 ， 这 里 键入 y 并 执行 (LIST 14.18 )。 


© LIST 14.18 迁移 文件 的 squash 


Do you wish to proceed? [yN] y 

Optumrzung 。 。 - 
Optimized from 3 operations to 2 operations. 

Created new squashed migration /path/to/myprj/polls/migrations/0001 squashed 

0003 auto 20141104 0236.py 4 
You should commit this migration but leave the old ones in place; 


the new migration will be used for new installs. Once you are sure 


(D nttps://docs.djangoproject.com/en/1.7/topics/migrations/Hdata-migrations 
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all instances of the codebase have applied the migrations you squashed, 
you can delete them. 

Manual porting required 
Your migrations contained functions that must be manually copied over, 
as we could not safely copy their implementation. 


See the comment at the top of the squashed migration for details. 


执行 后 生成 了 名 为 0001 squashed 0003 auto 20141104 0236.py 的 新 文件 。 这 个 
迁移 文件 相当 于 之 前 生成 的 0001, 0002, 0003 的 总 和 。 往 后 在 新 建 的 数据 库 中 执行 migrate 时 
会 使 用 这 个 新 的 迁移 文件 ， 而 在 已 有 数据 库 中 则 使 用 原来 的 迁移 文件 。 

不 过 ， 从 执行 squashmigrations 时 输出 的 信息 来 看 ， 我 们 需 EMEN 这 是 
J THER, 0003 auto 201141104 0236 是 手动 添加 的 。 新 建 数据 库 进 行 迁移 时 不 
需要 进行 数据 迁移 ， 所 以 我 们 可 以 将 数据 迁移 的 相关 处 理 从 0001 hr 0003 
auto 20141104 0236 中 删除 。 打 开 文 件 ， 删 除 operations 内 的 migrations.RunPython(…)。 另 外 ， 
用 于 添加 pub. date 的 迁移 文件 中 设置 的 当前 时 间 也 要 一 并 删除 (LIST 14.19 )。 





© LIST 14.19 0001 squashed 0003 auto 20141104 0236.py 


4 -*- coding: utf-8 -*- 


"ew e cutcuce Import wnicoce licerale 


from django.db import models, migrations 
import datetime 


from django.utils.timezone import utc 


# Functions from the following migrations need manual copying. 
# Move them and any dependencies into this file, then update the 
# RunPython operations to refer to the local versions: 


# polls.migrations.0003 auto 20141104 0236 


class Migration (migrations.Migration): 


EDLaCEH = [(o'polls", "0001 _ imitial'), Go'polls", "0002 poll pub cete!) ， d 
Go'polls", 10003 auto 20141104 0236) ] 

dependencies = [ 

] 

operations = [ 


migrations .CreateModel ( 
name-'Poll', 


fields-[ 
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(Cc, models. oie (verbose name=" Se ea 
tO Created=True, primary key=True) ) , d 
("euestcicm ctcext', mocels eame (max lLengrtn=200) ) ; 
# MRTA, AIRT 
= ("pub cace'!, mocelgs. DacetTimeriele a er me 
(2014, 1L, 4, l, MESSEN OMM yerbose name=" derce uie» d 
uotse models Darenm nepel (ver nnaeme las un 
I 
EIS 
^, 
bases= (models .Model,), 
m 
# 删除 以 下 被 注释 的 部 分 


# migrations.RunPython( 


# code=polls.migrations.0003 auto 20141104 0236.forward pub date 
oy one day, d 
# reverse code=polls.migrations.0003 auto 20141104 0236 .backward 
_ pul dace by one cay, d 
# Suse TUS, 
* oj 


新 建 数据 库 进 行 迁移 时 ， 只 需要 执行 polls 的 一 个 迁移 文件 。 


$ python manage.py migrate 
Operations to perform: 
Apply all migrations: admin, contenttypes, polls, auth, sessions 


Running migrations: 


Anpplvongseonteenttvpes-)9)T aO OR 

Applying eve 0001 mitial,... OK 

Applying ecmin. 0001 imitial, s» OK 

Applying polls.0001 squashed 0003 auto 20141104 0236... OK 
Applying sessions.0001 initial... OK 


LEELA AREARE es EAT E PAAR, YPEPBPBECK IERD JI H1] 
付出 以 及 出 现 操 作 失 误 的 风险 。 各 位 请 务必 斌 一 坛 ， 亲 目 体 验 其 效 末 。 


14.3 fixture replacement 


14.3.1 fr ze UT BOE ER 
在 第 8 章 中 ， 我 们 学 习 了 测试 的 相关 知识 ， 但 在 实际 编写 测试 代码 的 过 程 中 ， 有 时 必须 依 
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赖 于 模块 和 数据 ， 这 种 时 候 束 要 事先 准备 测试 数据 。 

Django 默认 能 够 将 测试 数据 事先 谈 和 人 人 数据库。Django 的 测试 配置 需 是 一 种 专门 用 来 让 
Django 谈 人 数据库 的 特定 格式 数据 文件 。 除 测试 之 外 ， 测 试 配置 硕 还 可 以 用 来 导入 开发 初期 阶 
段 需 要 用 到 的 数据 。 





€ 用 loaddata 命令 读 取 配置 器 
下 面 我 们 手动 创建 一 个 用 于 配置 絮 的 数据 文件 ， 然 后 读 取 它 。 这 里 需要 利用 前 面 生成 的 
Poll 模型 。 我 们 首先 在 工程 目录 下 创建 名 为 polls.json 的 文件 ， 文 件 内 容 如 LIST 14.20 所 示 。 





© LIST 14.20 polls.json 


[ 
{ 


mestre deed oleo obe. 


Medios des 

"fields": [( 
"edet mnn text", "Way mort use the fixture", 
vou cerce”; "2011-11-01 00:00: 007" 


j 
), 


umecelea oos 


Uoka: P 

tielas! d 
Ueguestion texts "Way nor use the Fixture2" , 
pulio Certes "2011-11-02 0000:0074" 


| 
j 


pk 指 模型 的 primary key 的 ID。 接 下 来 将 这 个 数据 文件 加 载 到 数据 库 中 (LIST 14.21 )。 


加 LIST 14.21 执行 loaddata 


$ python manage.py loaddata polls.json 


执行 完毕 后 ， 可 以 在 数据 库 的 polls poll 表 中 看 到 上 述 配置 器 提供 的 数据 。 各 位 可 以 使 用 
SQL 等 进行 查看 。 


€ 配置 怖 文件 的 存放 位 置 

在 工程 开始 阶段 ， 将 配置 靛 文件 放 在 工程 根 目 录 下 并 无 大 得 ， 但 是 随 春 应 用 规模 越 来 越 大 ， 
文件 目 然 也 越 来 越 多 ， 放 在 工程 根 日 录 下 将 很 难 维护 。 这 种 时 候 就 需要 修改 配置 各 文 件 的 存放 
位 置 并 进行 整理 。 整 理 有 以 下 2 个 方法 。 
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e 存放 在 对 应 应 用 的 fixtures 目录 下 
e 存放 在 settings.py 的 FIXTURE DIRS 指定 的 目录 下 


比如 我 们 在 应 用 目录 下 创建 了 fixtures 目录 C 例如 polls/fixtures/polls.json )， 我 们 就 可 以 将 该 
应 用 需要 谈 取 的 配置 希 文 件 放 在 这 里 。 这 样 一 来 ， 只 需要 执行 python manage.py loaddata polls. 
json 命令 即 可 读 取 配置 器 文件 。 另 一 种 就 是 设置 settings.py 中 的 FIXTURE DIRS， 该 变量 所 指 
目录 下 存放 的 配置 器 文件 将 被 视 为 读 取 对 象 。 如 果 想 把 任意 目录 作为 读 取 对 象 ， 建 议 使 用 这 种 
方法 。LIST 14.22 是 添加 与 manage.py 同 级 的 fixtures 目录 的 方法 。 


© LIST 14.22 FIXTURE DIRS 的 设置 


FIXTURE DIRS = |[ 
oos sogno EMDI NL eS 


€ 1t TestCase 中 使 用 配置 器 

Django 的 TestCase 能 够 目 动 谈 取 配置 硕 的 信息 。 只 要 在 TestCase 的 属性 里 设置 了 fixtures, 
所 指定 的 配置 器 文件 就 会 被 自动 读 取 。 在 LIST 1423 中 ， 我 们 读 取 了 名 为 polls.json 的 配置 器 ， 
使 得 测试 用 例 可 以 使 用 配置 带 内 记录 的 数据 。 


加 LIST 14.23 ”使 用 配置 器 的 TestCase 


from django.test import TestCase 


from polls.models import Poll 


class PollsTestCase(TestCase): 


Dgxtures -CbUposbiseysom| 


def setUp(self): 
# 一 般 的 测试 定义 


def testPoll(self): 
# 使 用 配置 器 的 测试 


€ 用 dumpdata 生成 配置 器 文件 

很 多 时 候 ， 纯 手动 编写 配置 器 文件 并 不 现实 ( 比如 需要 大 量 档案 或 者 多 种 不 同情 况 的 数据 
If). Django 有 生成 fixutre 文件 的 辅助 功能 ， 那 就 是 dumpdata 命令 。dumpdata 命令 可 以 用 
数据 库 里 的 数据 生成 配置 希 文 件 ( LIST 14.24 )。 








加 LIST 14.24 执行 dumpdata 


$ python manage.py dumpdata polls > polls.json 
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执行 完毕 后 生成 了 名 为 polls.json 的 配置 器 文件 。 内 容 与 之 前 用 loaddata 加 载 的 内 容 相 同 。 


14.3.2” 几 种 不 便 使 用 默认 配置 器 的 情况 
配置 器 用 起 来 很 方便 ， 但 编写 测试 代码 时 我 们 也 会 遇 到 配置 器 碍 事 的 情况 ， 下 面 就 举 几 个 
例子 来 说 明 一 下 。 





e 日 期 字段 会 变 成 特定 日 期 
我 们 再 来 看 看 上 面 提 到 的 polls.json， 会 发 现 pub data 列 的 日 期 是 固定 的 (LIST 14.25 )。 


© LIST 14.25 polls.json 


[ 
{ 


"model, "polls poll”, 


eu der 

"fields": ( 
womelsitno ne cr "Way not use the Fixture", 
woulo Carces "2011-11-01 00300: 007" 


j 
), 


nece] odis 


Us p 

oereide] 
euestion texts "Way noOE use the Fixturez" , 
puig Cates, "2011-11-02 00:00: 007" 


j 
j 





比如 我 们 的 测试 代码 硕 望 用 到 包含 “今天 的 日 期 ”的 Poll RAIS, sn 2T BO EL dS CIE TE 
的 pub data 修改 成 “今天 的 日 期 ” 才 行 。 在 这 种 需要 用 到 “今天 的 日 期 ”或 类 似 数据 的 情况 下 ， 
就 不 适合 用 配置 侣 来 准备 测试 数据 。 


e 配置 希 不 容易 维护 

举 个 例子 ， 我 们 给 Poll 模型 添加 新 的 属性 ( 列 ) 时 ， 需 要 对 polls.json 的 所 有 数据 添加 属性 。 
这 将 是 一 个 非常 费劲 的 工作 。 特 别 是 在 开发 新 的 应 用 时 ,模型 的 修改 往往 很 频繁 ， 要 想 维护 配 
置 融 文 件 使 之 能 跟 上 模型 的 变化 ， 成 本 通 篆 不 低 。 

可 见 ， 配 置 带 在 事先 准备 数据 方面 显得 十 分 便捷 ， 但 它 准备 的 数据 缺乏 灵活 性 和 可 维护 性 。 

接 下 来 我 们 将 学 习 一 个 能 解决 上 述 这 些 问 题 的 工具 




















factory boy。 
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14.3.3 ”如 何 使 用 factory boy 


factory boy" 可 以 帮助 我 们 生成 更 加 灵活 、 更 易 维护 的 配置 器 。 从 名 字 可 以 看 出 来 ， 它 是 
Ruby 经 典 工具 factory girl^ 的 Python 版。 

Django 的 配置 需 是 基于 文件 来 准备 数据 ， 而 factory boy 是 生成 对 应 于 数据 模型 的 Factory 
类 ， 因 此 它 能 够 动态 且 灵 活 地 为 我 们 准备 测试 数据 。 这 种 不 以 文件 形式 提供 配置 项 ， 而 是 提供 
能 训 来 同样 效果 的 数据 模型 的 工具 称 为 fixture replacement。 除 文 持 Django 外 ，factory boy 还 文 
持 其 他 O/R 映射 工具 。 

这 里 我 们 用 pip 安装 factory boy(LIST 14.26 )。 














© LIST 14.26 安装 factory_boy 


$ pio install tTactory-boy 
本 书 使 用 了 factory boy 的 2.4.1 版 本 。 


€ Factory 
Factory 对 于 将 目标 对 象 实例 化 时 所 需 的 一 系列 属性 进行 了 定义 。 在 命名 Factory 类 时 ， 需 
要 让 使 用 者 能 够 通过 我 们 赋予 的 名 称 推 测 出 其 目标 对 象 的 类 (LIST 14.27 )。 





Ej LIST 14.27  PollFactory 类 


LOrE EaOEOLY 

from django.utils import timezone 

from polls.models import Poll 

class PollFactory (factory .django.DjangoModelFactory): 
cuestion text = 'factory GUestTLon! 


puo Certe = Timezone now l) 


class Meta: 


model = Poll 


e 构建 策略 
factory boy 支持 多 种 不 同 的 构建 策略 。 构 建 策略 是 确定 数据 模型 生成 状态 的 方法 。 在 测试 
用 例 中 ， 如 果 需 要 使 用 不 同 状 态 的 目标 对 象 ， 就 会 用 到 它们 (LIST 14.28 )。 








(D https://github.com/rbarrois/factory boy 
2) https://github. com/thoughtbot/factory girl 
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回 LIST 14.28 支持 的 构建 策略 


# 返回 没有 save 的 Poll 实例 
DOLL = Pollractory tust 


# 返回 已 save 的 Poll 实例 
poll = PollFactory.create() 


# 以 字典 形式 返回 生成 Poll 实例 时 所 用 的 属性 
attributes = PollFactory.attributes ( ) 


# 返回 所 有 属性 桩 代码 化 后 的 对 象 
grub Pol sci cn stub |) 


直接 实例 化 Factory 类 时 ， 其 运行 效果 与 create 0 相同 (LIST 14.29 )。 


© LIST 14.29 Factory 类 的 实例 化 


poll = PollFactory() #=> 5 PollFactory.create() 效果 相同 


生成 实例 时 可 以 通过 传递 关键 字 传 值 参数 的 方式 覆盖 原 有 属性 值 ， 而 无 需 关 心 使 用 的 构建 
策略 ( LIST 14.30 )。 








E LIST 14.30 ”覆盖 属性 


POLL = Pollractory., Create (guestion text=" Changed. questien!" ) 


€ 延迟 计算 属性 

虽然 我 们 在 定义 Factory 的 时 候 已 经 添加 了 毅 态 的 属性 ， 但 有 些 属 性 (关联 的 数据 模型 、 需 
要 动态 生成 的 属性 等 ) 需要 在 每 次 生成 实例 时 进行 设置 。 准 备 这 类 属性 束 需 要 用 到 Lazy Attribute 
了 (LIST 14.31 )。 











回 LIST 14.31 LazyAttribute 的 示例 


class UserFactory (factory.django.DjangoModelFactory) : 
first _ name = '"Beproud!' 
last name = 'Taro' 
email - factory.LazyAttribute (lambda a: 
' (0). (1) eexample.com'.format(a.first name, 
a.last_name) .lower () ) 
class Meta: 


model = User 


UserFactory().email #=> beproud.taro@example .com 
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e 序列 
根据 特定 格式 需要 用 到 连续 的 属性 值 时 ， 可 以 使 用 序列 ( Sequence ) ( LIST 14.32 )。 


© LIST 14.32 Sequence 


class UserFactory(factory.django.DjangoModelFactory): 


email = factory.Sequence(lambda n: 'personí(0jGeexample.com'.format (n)) 


class Meta: 


model = User 


UserFactory().email d => 'personOGexample.com' 


UserFactory().email # => 'personlGexample.com' 


基本 的 内 容 到 这 里 就 了 解 清楚 了 。 接 下 来 我 们 看 看 如 何 用 factory. boy 解决 Django 中 的 配 
置 内 不 好 用 的 问题 。 





14.3.4 消除 “不 便 使 用 黑 认 配置 怖 的 情况 


© 解决 “日 期 字段 会 变 成 特定 日 期 ”的 问题 
按照 LIST 14.33 所 示 定 义 PollFactory 类 ， 然 后 为 测试 用 例 的 属性 配 上 合适 的 日 期 ， 这 样 我 
们 就 能 得 到 想 要 的 数据 模型 了 。 


Ej LIST 14.33 ”设置 灵活 的 日 期 字段 
class PollFactory(factory.django.DjangoModelFactory): 
question text = Re ederet question! 
# 配 上 与 测试 匹配 的 日 期 


pulo carce = timezone now TO 


class Meta: 


madel = Poll 


# 还 可 以 在 生成 实例 时 设置 


POLL = POllkactory. Create (puo cdace=timezene . now () ) 


@ 解决“ 配置 器 不 容易 维护 ”的 问题 

配置 器 不 易 维护 的 问题 怎么 解决 呢 ? Django 的 配置 器 在 给 模型 添加 列 时 ， 需 要 对 配置 吉 的 
所 有 数据 进行 修改 ， 但 如 果 使 用 factory boy， 则 只 需要 给 Factory 类 添加 列 即 可 。 

只 需 进行 下 述 修改 ， 所 有 通过 PollFactory 生成 的 Poll 模型 中 就 都 添加 了 user name 列 
( LIST 14.34 )。 
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© LIST 14.34 添加 列 


class PollFactory (factory .django.DjangoModelFactory): 


question tekt = "factory question ' 
# OXRDUSSAU 

user neame Unc san' 

pulo dete = timezone. now) 


class Meta: 


model = Poll 


通过 上 面 的 内 容 可 以 看 出 ，Django 的 配置 器 对 于 简单 的 测试 、 事 先 准备 数据 等 用 途 而 言 十 分 
便捷 ， 但 要 想 在 实际 开发 中 持续 地 实施 测试 ， 还 是 建议 使 用 更 加 灵活 且 易 于 维护 的 factory boy. 














14.4 Django Debug Toolbar 





接 下 来 了 解 一 下 在 用 Django 开发 应 用 的 过 程 中 辅助 调试 的 Django Debug Toolbar. 





Django Debug Toolbar 的 简介 








用 Django 进行 开发 时 ， 各 位 是 否 想 过 “显示 某 个 页 面 的 过 程 中 总 共 发 送 了 哪些 SQL” 呢 ? 
其 实 只 要 使 用 Django Debug Toolbar" ， 我 们 就 可 以 在 开发 Web 页 面 的 同时 查看 “发 送 了 哪些 
SQL” “处 理 花 费 了 多 少时 间 ” 等 信息 了 

除了 SQL 之 外 ,使 用 Django Debug Toolbar 还 可 以 查看 许多 在 开发 过 程 中 想 要 查看 的 信息 。 
下 面 是 除 SQL 之 外 可 以 查看 的 项 目 。 














Versions Django 的 版 本 

Time 显示 视图 所 用 的 时 间 

Settings settings.py 中 描述 的 设置 值 

Headers HTTP 请 求 / 响 应 的 头 信息 

Request GET/POST/Cookie/Session 的 变量 信息 
StaticFiles 静态 文件 的 相关 信息 

Templates 模板 的 相关 信息 

Cache 缓存 框架 的 访问 信息 














Signals Django 的 内 置 signal 信息 











Logging 被 记录 的 日 志 信 息 


(D https://github.com/django-debug-toolbar/django-debug-toolbar 
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这 里 我 们 来 了 解 一 下 几 个 可 查看 的 信息 。 另 外 ， 本 书 使 用 了 Django Debug Toolbar 的 1.2.2 
版 本 。 现 在 来 看 看 它 的 具体 使 用 方法 ， 先 从 安装 开始 。 











@ 安装 
$ pip install django-debug-toolbar 
安装 完成 之 后 在 settings.py 中 添加 如 LIST 14.35 所 示 的 内 容 。 


回 LIST 14.35. INSTALLED APPS 内 添加 的 内 容 


INSTALLED APPS = ( 


'django.contrib.staticfiles' H ftF'debug toolbar! Z BJ E 


'debug toolbar' 4 < MJ 


XEM 'django.contrib.staticfiles' 要 设置 在 'debug toolbar! XB. 25, 
Django 1.7 默认 设置 了 'django.contrib.staticfiles'. 


€ 查看 Debug Toolbar 
设置 完 settings.py 之 后 重启 Django, Bici ss E REAL 14.4 所 示 的 调试 用 工具 栏 。 











Django 管理 





Headers 


Request 


SQI 


Static files 


Templates 


Cache 





14.4 Debug Toolbar 


348 | 第 4 部 分 加 速 开 发 的 技巧 








不 需要 显示 Debug Toolbar 时 ， 点 击 右上 角 的 Hide 即 可 隐藏 工具 栏 。 


e SQL 


如 图 14.5 所 示 ， 我 们 能 够 查看 当前 视图 内 发 送 的 SQL 语句 。 除 此 之 外 还 有 SQL 的 Explain 
的 执行 结果 以 及 发 送 SQL 前 的 Stacktrace 等 信息 。 





SQL queries from 1 connection Hide » 


l default 
0.77 ms (3 queries ) 


Versions 


QUERY TIMELINE TIME (MS) 动作 - 
| [s] SELECT .+ FROM 'django. session?" WHERE Tr 0.38 Sel Hia) 


("django_session"."session_key" = 











Expl 
""]m5rm29wx358wl5l81jopnfhlvog2t5u"" AND 
"django session"."expire date" > ''2016-08-25 06:51:46.058967'"") Settings 
| [E] SELECT --- FROM "auth user" WHERE "auth user"."id" = '1' E 0.17 Sel 
Expl Headers 
| [E] SELECT --- FROM 'django admin log" INNER JOIN "auth user" ON EE o Sel 
("django admin log"."user id" = "auth user"."id") LEFT OUTER JOIN Expl Request 
"django content type" ON ("django admin log"."content type id" = 
"django content type"."id") WHERE "django admin log"."user id" = 
'1' ORDER BY "django admin log"."action time* DESC LIMIT 10 sQL 
Static files 
Templates 
Cache 
Signals 
ions 会 显示 当前 视图 使 用 的 模块 的 版 本 信息 (图 ) 
Versions Z lib zs 24 Bj qi VERSER Fi dh 14.6 ); 
Versions Hide » 
Versions 
NAME VERSION 
Debug Toolbar 1.2.2 
Django 1741 | 
Python 2.7.6 


Settings 


Headers 





14.6 Versions 


€ 时 间 


如 图 14.7 所 示 ,“ 时 间 ” 能 查看 显示 当前 视图 所 消耗 的 时 间 。 我 们 来 简单 看 一 下 其 中 的 主 
要 项 目 。 








e User CPU time: 从 接 到 请 求 到 演 染 完 页 面 的 时 间 
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e System CPU time; MIRR HE SIT AS AFEN, HTTP i pw 3f3 Iul £5 e P vg Pr HRS EST D] 
e Total CPU time: User CPU time + System CPU time 的 总 和 ， 即 从 接 到 请 求 到 返回 啊 应 所 用 
的 时 间 








时 间 Hide » 


Versions 


Resource usage 





RESOURCE VALUE Hi] 
User CPU time 44.000 msec 
System CPU time 0.000 msec 
Total CPU time 44.000 msec Settings 

| Elapsed time 47.396 msec 
Context switches 0 voluntary, 1 involuntary Headers 
Browser timing eee 
TIMING ATTRIBUTE TIMELINE MILLISECONDS SINCE NAVIGATION START (-LENGTH) 
domainLookup 0 («0) SQL 
connect 0 (+0) 
request 1 (+119) 
response 120 (+0) Static files 
domLoading 120 (+133) 
dominteractive 231 
domContentLoadedEvent 238 (+7) Templates 
loadEvent 253 (40) 


Cache 





14.7 ”时 间 


@ Settings 
Settings 可 以 列表 查看 Django 的 settings.py 内 设置 的 值 (HE) iX IB BE EEEEITJ HUE WE, 
因此 不 会 显示 settings.py 中 定义 的 函数 等 内 容 (图 14.8 )。 











Settings from mysite. settings Hide » 
DEFAULT CONTENT TYPE u'text/html' Versions 
DEFAULT EXCEPTION REPORTER FILTER u'django.views.debug.SafeExceptionReporterFilter' 
DEFAULT FILE STORAGE u'django.core.files.storage.FileSystemStorage' 
DEFAULT FROM EMAIL u'webmasterglocalhost' RT iB] 
DEFAULT INDEX TABLESPACE u'' 
DEFAULT TABLESPACE im^" . 
DISALLOWED, USER. AGENTS [] Settings 
EMAIL BACKEND u'django.core.mail.backends.smtp.EmailBackend' 
EMAIL HOST u' localhost Headers 
EMAIL HOST PASSWORD u'*sestesstet otro ern? Request 
EMAIL HOST USER u'' 
EMAIL PORT 25 
EMAIL SSL CERTFILE None sQL 
EMAIL SSL KEYFILE U'****tksiitksik*ksrtikxk? 
EMAIL SUBJECT PREFIX u'[Django] ' 
EMAIL TIMEOUT None Static files 
EMAIL USE SSL False 
EMAIL USE TLS False 
FILE CHARSET u'utf-8' Templates 
FILE UPLOAD DIRECTORY PERMISSIONS None 
FILE UPLOAD HANDLERS [u'django.core.files.uploadhandler.MemoryFileUploadHandler', 

u'django.core.files.uploadhandler.TemporaryFileUploadHandler'] Cache 
FILE UPLOAD MAX MEMORY SIZE 2621440 
FILE UPLOAD PERMISSIONS None 
FILE UPLOAD TEMP DIR None Signals 
FIRST DAY OF WEEK e 





14.8 Settings 


€ Headers 
Headers 里 可 以 查看 HTTP 请 求 / 啊 应 的 头 信息 ( 图 14.9 )。 
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Headers 


Request headers 


Key 

Accept 

Accept-Encoding 
Accept-Language 
Cache-Control 

Connection 

Cookie 

Host 
Upgrade-Insecure-Requests 
User-Agent 


Response headers 


Key 
Content-Type 
Vary 


X-Frame-Options 
WSGI environ 
Since the WSGI environ inherits ti 


Key 


€ Request 


Value 

text/html, application/xhtml*xml,application/xml;q-0.9.image/webp,*/*:q-70.8 

gzip, deflate, sdch 

en-US,en;q-0.8,zh-CN;q-0.6.zh;q-0.4 

max-age=0 

keep-alive 

=> see Request panel 

192.168.56.101 

1 

Mozilla/5.0 (Windows NT 6.1; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/50.0.2661.102 Safari/537.36 


Value 

text/html; charset-utf-8 
Cookie 

SAMEORIGIN 


he environment of the server, only a significant subset is shown below. 


Value 


14.9 Headers 


Request 可 以 查看 HTTP 请 求 发 送 的 GET/POST/Cookie 的 内 容 


用 的 视图 的 信息 (图 14 


.10 )。 


Hide » 


Versions 


时 间 


Settings 
Headers 


Request 
SQL 
Static files 
Templates 
Cache 


Signals 


. Session 的 内 容 ， 





Request 


View information 
VIEW FUNCTION 
polls.views.dashboard 
Cookies 


VARIABLE 


'csrftoken' 

'dját' 

'sessionid' 
Session data 


VARIABLE 
u' auth user backend' 
u' auth user hash' 


u' auth user id' 


No GET data 


No POST data 


@ Static files 


ARGUMENTS KEYWORD ARGUMENTS 
Q {} 


URL NAME 


polls.views.dashboard 


VALUE 
'guwSC9376FAhmhpORSCL8zNkDTw7xH4iVRYi4zBzDglHba6TxM2ydvocxvHutTTB* 
'show' 


'7m5rm29wx358w15181jopnfhlvog2t5u' 


VALUE 
u'django.contrib.auth.backends.ModelBackend"* 
u' 7a4fe4f983cf4b6d5fe909a54b74602ecdec3215' 
u'1' 


14.10 Request 


Hide > 


Versions 


时 间 


Settings 
Headers 


Request 


SQL 


Static files 


Templates 


Cache 


Signals 











Static files 可 以 查看 通过 django.contrib.staticfiles 获取 的 静态 文件 列表 ， 以 及 staticfiles 获取 


文件 时 的 对 和 象 日 录 列 表 


(图 14.11 )。 
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Static files (61 found, 10 used) Hide » 
Versions 
Static file paths 
无 ` 
时 间 ] 
Static file app 
django.contrib.admin - 
Settings 
Static files 
Headers 
admin/css/base.css 
/usr/local/lib/python2.7/dist-packages/django/contrib/admin/static/admin/css/base.css Request 
admin/css/changelists.css 
/usr/local/lib/python2.7/dist-packages/django/contrib/admin/static/admin/css/changelists.css 
SQL 
/usr/local/lib/python2.7/dist-packages/django/contrib/admin/static/admin/js/core.js 
admi n : 
/usr/local/lib/python2.7/dist-packages/django/contrib/admin/static/admin/js/vendor/jquery/jquery.js Static files 
admin/js/jquery.init js 
/usr/local/lib/python2.7/dist-packages/django/contrib/admin/static/admin/js/jquery.init.js 
z : z 3 Templates 
admin/js/admin/RelatedObjectLookups.js p 








/usr/local/lib/python2.7/dist-packages/django/contrib/admin/static/admin/js/admin/RelatedObjectLookups.js 


14.11 StaticFiles 


€ Templates 


Templates 里 可 以 查看 当前 视图 使 用 的 模板 (包含 继承 关系 ) 以 及 传 给 模板 的 Context, 
Context processor 的 列表 (图 14.12 )。 





Templates (7 rendered) Hide » 


a Versions 


Template paths 


/var/www/mysite/templates 


/usr/local/lib/python2.7/dist-packages/debug toolbar/templates 时 间 
Templates 
Settings 
admin/change list.html g 
/usr/local/lib/python2.7/dist-pack /dj trib/admin/t lates/admin/ch | |ist.html 
d ra on ist-packages/django/contrib/admin/templates/admin/change list.htm Headers 
admin/base site.html 


f : : : : ' i Request 
/usr/local/lib/python2.7/dist-packages/django/contrib/admin/templates/admin/base_site.html 


» loggie context 


admin/base.html 
/usr/local/lib/python2.7/dist-packages/django/contrib/admin/templates/admin/base.html 


» Toggle context 


admin/search form.html 
/usr/local/lib/python2.7/dist-packages/django/contrib/admin/templates/admin/search form.html 
» Toggle context 

admin/date hierarchy.html 
/usr/local/lib/python2.7/dist-packages/django/contrib/admin/templates/admin/date hierarchy.html 


» Toggle context 


admin/change list results.html 
/usr/local/lib/python2.7/dist-packages/django/contrib/admin/templates/admin/change list results.html 


SQL 


Static files 


Templates 


Cache 


» loggle context 


panes Signals 
/usr/local/lib/python2.7/dist-packages/django/contrib/admin/templates/admin/pagination.html g 


* Toggle context 





14.12 Templates 


€ Cache 
Cache PJ UEA ?4 mij d p fi HIR XE m Js E 14.13 )。 
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Cache calls from 1 backend 


Wwe 

pu 
TOTAL CALLS TOTAL TIME CACHE HITS CACHE MISSES 
0 0 ms 0 0 
Commands 


ADD GET SET DELETE CLEAR GET MANY SET MANY DELETE MANY HAS KEY INCR DECR INCR VERSION . DECR VERSION 


0 0 0 0 0 0 0 0 0 0 0 0 


14.13 Cache 


€ Logging 


假设 polls 应 用 的 视图 中 输出 了 如 LIST 14.36 所 示 的 调试 日 志 ， 


14.14 所 示 的 日 志 。 


© LIST 14.36 Logging 的 设置 示例 


import logging 


logger = logging.getLogger( name ) # name 处 代入 模块 路 径 


cet detail (request, POLL Lel) < 
POLL = get object or 404 (POLL, laoll iel) 
logger. imnto(' Poll: 58", POLL, 1€!) 
return TemplateResponse (request, 'polls/detail.html', 


pola apo) 


Hide » 


Versions 


mjia 


Settings 


Headers 


Request 


SQL 


Static files 


Templates 


Cache 





那么 浏 览 各 上 就 会 显示 如 图 


'polls.views' d 





Log messages 


Level 时 间 Channel Message Location 
INFO 08:08:48 11/05/2014 polls.views Poll: 1 Niarwww/mysite/polls/views.py:12 


14.14 Logging 


@ Intercept redirects 








分 选 工 具 栏 下 方 的 “Intercept redirects” 和 选项， 网 页 的 重 定 回 将 被 拦截 。 这 项 功能 可 以 帮助 
我 们 确认 重 定 回 的 时 间 点 、 查 看 返回 重 定 回 啊 应 的 视图 内 都 执行 了 哪些 处 理 。 
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Hide » 


302 Found 


Static files 


Location: |/ 


The Django Debug Toolbar has intercepted a redirect to the above URL for debug view gurpuses Y 


the above link to continue with the redirect as normal. 


Cache 


Signals 


Logging 


Intercept redirects 





14.15 Intercept redirects 


€ 自 定义 显示 

工具 栏 的 显示 可 以 根据 开发 应 用 的 情况 与 阶段 进行 自 定义 。 自 定义 的 方法 很 简单 ， 只 要 在 
settings.py 中 添加 DEBUG TOOLBAR PANELS 项 ,按照 自己 的 需要 对 其 中 内 容 进 行 重 排 或 改 
为 注释 ， 即 可 修改 工具 栏 的 显示 项 目 (LIST 14.37 )。 








回 LIST 14.37 DEBUG_TOOLBAR_PANELS 的 设置 


DEBUG TOOLBAR PANELS = | 
'debug toolbar.panels.versions.Versionspanel', 
debug _ tOOlbart. panels. timer, TimerpPeanel" , 
! e stets 16e xol. oyetr segetem Tusc ee em panen 
üdebudgecootibse pone sealensm eal 
volelouemeoon en nonc poseen cc De 
GEIOuUg aloaE nls so omnes 
' debug tOOlbar. panels. em Starcichilespanel", 
olelmumemeoeonlen mcllcememplicweccemplicue pom 
Ncc bum pou panels. cache, CachePanel" , 
'debug_toolbar .panels.signals.SignalsPanel', 
ldelbusgmeoolbsc en ee en 


Valelouenmeool a nme coucou 


14.5 小结 


本 章 我 们 聚焦 基于 Python 开发 的 Web 应 用 框架 Django， 对 其 架构 进行 了 学 习 ， 并 了 解 了 
一 些 有 助 于 开发 的 库 。 
如 果 要 开发 的 Web 应 用 很 简单 ， 那 么 默认 设置 的 Django 也 就 够 我 们 用 了 。 不 过 ， 一 旦 我 
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们 希望 让 开发 或 运营 的 Web 应 用 更 加 健壮 和 安全 (业务 方面 尤为 多 见 ) “这 里 做 的 还 不 够 ”“ 那 
里 再 改善 一 点 就 好 了 ”之 类 的 需求 也 就 多 了 起 来 。 正 如 本 章 所 讲 的 那样 ， 很 多 时 候 ， 可 重复 利 
用 的 Django 应 用 和 Python 库 可 以 帮助 我 们 解决 或 者 一 定 程 度 上 改善 这 些 问题 。 

当然 ， 实 际 开发 中 方便 好 用 的 库 远 不 止 本 章 介 绍 的 这 些 。 下 面 我 们 再 简单 了 解 几 个 。 








e django-extensions 

EHEM, AETR, REREN Django EAREN fi. 
° sei 

ne 过 专用 模板 标签 和 管理 命令 简化 缩 略图 的 生成 与 显示 。 
° bpmappers” 

简化 模块 映射 的 Python 库 。 第 15 章 将 对 其 作 详细 介绍 。 








(D nttps://github.com/django-extensions/django-extensions 
(2) https://github.com/mariocesar/sorl-thumbnail 
© https://bitbucket.org/tokibito/python-bpmappers 
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各 位 在 开发 应 用 的 过 程 中 有 没有 想 过 “这 个 处 理 是 不 是 有 人 实现 过 ”“ 这 个 东西 该 怎么 实 
现 ” 之 类 的 问题 呢 ? 这 种 时 候 最 好 先 去 Google 上 看 看 是 否 有 现成 的 模块 可 用 。 如 果 只 需要 
Python 模块 ， 可 以 到 PyPI 上 去 找 。 发 现 有 能 拿 来 就 用 的 模块 绝对 是 一 大 好 事 。 确 认 一 下 许可 
证 ， 只 要 没 问 题 束 放 心 去 用 吧 。 

如 来 能 顺利 缩短 开发 时 间 目 然 古 好 事 一 桩 ,但 现实 中 往往 不 那么 顺利 ， 比 如 找 不 到 好 用 的 
模块 ,或 是 找到 模块 却 不 知道 蚊 么 用 ， 查 询 用 法 又 花 挥 许多 时 间 每 。 最 理想 的 情况 是 事先 知道 
这 些 好 用 模块 的 适用 场合 及 使 用 方法 ， 以 便 有 需要 时 直接 拿 来 用 。 因 此 我 们 要 从 平时 就 注意 积 
累 ， 多 通过 书籍 、 网 络 博客 、RSS 订阅 等 途径 收集 相关 信息 。 

本 章 的 目的 就 是 充当 各 位 的 信息 源 ， 为 各 位 介绍 一 些 方便 好 用 的 Python 模块 。 









































15.1 轻松 计算 日 期 


日 期 是 大 部 分 系统 部 要 用 到 的 ， 但 是 它 的 计算 比较 复杂 ， 因 此 很 容易 出 现 Bugs FET m 
质 软件 时 要 尽量 避免 复杂 的 操作 。 使 用 dateutil 模块 可 以 让 我 们 用 人 简单 的 描述 来 完成 复杂 的 日 期 
计算 。 











dateutil 








http://labix.org/python-dateutil 





15.11 日 期 计算 的 复杂 性 
首先 我 们 了 解 一 下 日 期 计算 中 容易 出 Bug 的 地 方 。 


@ “1 个 月 后 ”是 哪 一 天 

遇 到 “1 月 1 日 的 1 个 月 后 是 哪 一 天 ”的 问题 时 ， 大 部 分 人 都 会 回答 “2 月 1 日 "。 那 么 ， 
换 成 “1 月 31 日 的 1 个 月 后 是 哪 一 天 ”， 答 案 又 是 怎样 呢 ? 臣 介 我 们 会 得 到 “2 月 28 日 或 29 
H” “3 月 3 日 ” “2 月 31 日 ”等 多 种 回答 。 在 开发 系统 的 过 程 中 ， 如 采用 了 “1 个 月 后 ”这 种 
模糊 不 清 的 表述 ， 开 发 者 之 间 很 可 能 产生 认识 上 的 分 疏 ， 最 终 开发 结果 就 会 出 现 Bug。 在 这 个 
例子 中 ,“30 天 之 后 ”“ 下 个 月 的 最 后 一 天 ”等 表述 都 比 “1 个 月 后 ”清楚 得 多 ， 它 们 能 准确 指 
定 一 个 日 期 极 大 地 避免 歧义 。 
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@ 求 下 个 月 的 最 后 一 天 
首先 我 们 用 Python 标准 模块 datetime 的 timedelta 来 编写 一 个 计算 “下 个 月 最 后 一 天 ”的 程 
序 (LIST 15.1 )。 











© LIST 15.1 datetime dateutil 1.py 


m coding: eu 


from datetime import datetime, timedelta 


cder main () s 

ar en e NB 大 

now time = datetime.now () 

# 获取 下 下 个 月 第 一 天 的 目 期 对 象 

tiret Cay of atter two month = datetime ewm c cR 
now time.month + 2, 
1) 

# 获取 下 个 月 最 后 一 天 的 日 期 对 象 

last day oi next month = \ 

cM Cay Ot atter two month =- timedelta (cdays=1) 
# 输出 结果 
prine last Cay or nekt month. cate () 


if o ā name _— == | mainm ': 


main () 
执行 上 述 代 码 会 得 到 如 LIST 15.2 所 示 的 结 


© LIST 15.2 ”执行 结果 


Smeenoneeaee Nae ny 
2012=02=29 

















这 里 我 们 通过 “下 下 个 月 第 一 天 的 前 一 天 ”算出 了 “下 个 月 的 最 后 一 天 ”。 虽 然 这 在 看 上 去 
没有 什么 问题 ， 但 实际 上 ， 在 求 “ 下 下 个 月 的 第 一 天 ”时 ， 我们 忘记 考虑 年 份 的 更 迭 了 。now_ 
time.month 可 以 取 1 ~ 12 的 值 ， 而 这 个 值 加 上 2 有 可 能 达到 13、14。 因 此 ， 这 个 程序 在 过 到 
11 月 和 12 月 时 会 发 生 例外 。 我 们 想 要 的 运行 情况 是 now_time.month 为 11 和 12 时 增 算 一 年 。 
问题 修正 后 的 代码 如 LIST 15.3 所 示 。 





© LIST 15.3 datetime dateutil 2.py 


u Coding: ubf-8 


from datetime import datetime, timedelta 


def main(): 


# 下 个 月 最 后 一 天 = 下 下 个 月 的 前 一 天 


now time = datetime.now () 
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# 获取 下 下 个 月 第 一 天 的 日 期 对 象 ( 考虑 跨 年 问 题 ) 


2 now Cime momeha im do 


Tirst Cay Ot after Ewo monta = 


else: 


"ebeewe Cay Of after tyo monta = 


il 局 到 
last day of next month ~ \ 


Tirst Cey OF erter CWO Monta = 


# 输出 结果 


datetime (now time 
now time 


1) 
datetime (now time 


now time 


i) 


timedelta (days-1) 


printe last Cay of next month cate (C) 


it MEMO _ =s '_ main  ': 


main () 





year + 二) 


.month —- 2 - 12, 


.year, 


.month + 2, 


204 


可 见 ， 日 期 计算 常 肖 会 遇 到 复杂 的 边界 问题 ， 很 容易 出 现 Bug。 下 面 我 们 用 dateutil 模块 来 


简化 这 段 代 码 。 


15.1.2 EK dateutil 


用 pip 命令 安装 dateutil 模块 ， 代 码 如 LIST 15.4 所 示 。2014 年 12 月 初 的 dateutil 最 新 版 本 


为 2.3。 


© LIST 15.4 用 pip 命令 安装 dateutil 模块 


9 pip arista pychonm-derceucil==2,3 





使 用 dateutil 模块 的 relativedelta KH, d] ] n] ELE] 2H LIST 15.5 所 示 的 代码 获取 前 面 提 





到 的 “下 个 月 最 后 一 天 ”。 


© LIST 15.5 datetime dateutil 3.py 


m Coding ee 


from dateutil.relativedelta import relativedelta 


from datetime import datetime, timedelta 


def main(): 
# Fr HmAa A- F HAEN A 


now time = datetime.now () 
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# 输出 下 个 月 最 后 一 天 
last day of next month = \ 


now cime + relartcivyvecelta(months=2, Cdey=1, cays==1) 
# 输出 结果 


printe last cay of nert month. cate () 


ilt ames c main "s 


main () 


relativedelta Ej timedelta 一 样 ， 可 以 对 datetime 对 象 进 行 加 减 运算 。 关 键 字 传 值 参数 方面 有 
day, second, hour 等 单数 型 和 days, seconds, hours 等 复数 型 可 供 选 择 。 单 数 型 的 传 值 参数 为 
指定 数值， 复数 型 的 传 值 参数 为 指定 增 减 幅 度 。 





e rrule 
接 下 来 要 介绍 的 是 rrule， 它 可 以 获取 符合 指定 规则 的 日 期 对 象 。 比 如 LIST 15.6, 3xxEzf S 
的 作用 是 获取 2012 年 1 月 1 日 到 2012 年 2 月 1 日 的 周一 和 周三 的 日 期 对 象 并 输出 。 





© LIST 15.6 dateutil_rrule.py 
qoecosdume ul 
from datetime import datetime 


from dateutil.rrule import rrule, DAILY, MO, WE 


def main(): 

# 生成 rrule 对 象 

rrule obj - rrule(DAILY, 4 &X 
byweekday-(MO, WE),  & 周一 、 周 三 
diestart-datetime(2012,; 1, 41). 3 20UT2 5E 1 HJ X Hus 
until datetime 2012 02 D) #202 reos Ee uide 

# 逐个 取出 符合 条 件 的 日 期 对 象 并 显示 在 屏幕 上 

tOr CE in rrule aoge 


perime Cie 


rrule PRA —- Pe BEAZOR M, n AE YEARLY (Æ), MONTHLY ( 每 月 )、 
WEEKLY (4J) DAILY ( 每 天 )、HOURLY (每 小 时 )、MINUTELY ( 每 分 钟 ), SECONDLY 
(每 秒 )。 其 他 条 件 通过 选项 指定 。 以 LIST 15.6 中 的 代码 为 例 ，byweekday 指定 了 星期 几 ， 
dtstart 指定 了 开始 日 期 ，until 指定 了 终止 日 期 。 

实际 执行 结果 如 LIST 15.7 所 示 。 


© LIST 15.7 执行 结果 


$ python cacet ule ,oy 


2012-01-02 
ZOL- QE 
2012-01-09 
2012-01-11 
2012-01-16 
AOLA OM TR 
2012-01-23 
ZO Dun 
POMPONIO 
2012-02-01 


WO 
O0 s 00 e 
OO 


00 
00 
00 
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15.2 简化 模型 的 映射 





近年 来 ，Web 系统 为 保证 服务 器 与 客户 端 、 服 务 器 与 服务 器 之 间 的 协作 ， 越 来 越 多 地 开始 
提供 JSON, XML 等 格式 的 API。 在 这 类 API 的 内 部 处 理 中 ，O/R 映射 工具 生成 的 对 象 要 序列 


化 成 JSON 或 XML 格式 。 


开发 API 时 ，API 提供 的 JSON 数据 的 结构 必须 与 O/R 映射 工具 生成 的 模型 对 象 的 结构 一 


致 ， 否 则 就 会 出 现 问题 。 


这 种 问题 称 为 阻抗 失 配 ( Impedance Missmatch )。 这 种 时 候 ， 如 采 模 型 





层级 结构 比较 复杂 ， 那 么 模型 的 重复 利用 、 代 码 的 可 该 性 、 维 护 成 本 等 方面 都 会 遇 到 困难 。 
这 里 我 们 学 习 一 个 能 有 效 解决 阻抗 失 配 的 模块 一 一 bpmappers。 


bpmappers 





http://bpmappers.readthedocs.io/en/latest/ (HX) 


https://pypi.python.org/pypi/bpmappers 








15.2.1 


模型 映射 的 必要 性 


在 实际 开发 系统 的 过 程 中 ，API 规定 的 键 名 与 值 的 对 应 关系 很 少 能 与 数据 模型 的 结构 一 致 。 
接 下 来 ， 我 们 以 使 用 JSON 格式 返回 响应 的 API 为 例 进行 学 习 。 现 在 假设 系统 中 使 用 了 如 LIST 
15.8 所 示 的 User 类 的 数据 模型 。 


回 LIST 15.8 User 类 


class User(object): 


cet init _ (self, 





id, password, nickname, age): 
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self.id = id # HP ID 
self.password = password # 密码 
self.nickname = nickname 4 昵称 


self.age = age # FK 


这 个 数据 模型 拥有 “用 户 ID R” “昵称 *“ 年 龄 ”这 4 个 值 。 而 在 我 们 生成 的 API 中 ， 
只 将 “用 户 ID” 和 “昵称 ”两 个 值 包含 到 响应 之 中 。 该 API 通过 如 下 ISON 格式 的 响应 公开 了 
User 类 的 数据 。 





("user id": " HP'!ID", "user nickname": Tiki") 


Bé Po —^ ERA, EFIE DGKSUC—4- User 类 的 对 象 ， 并 将 其 转换 为 JSON 格式 
( LIST 15.9 )。 





© LIST 15.9 将 User 类 对 象 转换 为 JSON 格式 的 函数 


import json 


det convert uger tco Jeon(ueser) 


" 获取 一 个 User 对 象 并 返回 JSON 


# 生成 用 于 转换 格式 的 字典 对 象 
Uere ccm | 
'user id': user.id, # 使 用 名 为 user id 的 键 
'user nickname': user.nickname, # 使 用 名 为 user_nickname 的 键 


json.dumps(user dict) 4 转换 为 JSON 
iX KROM user dict 变量 生成 字典 对 象 ， 质 上 是 给 模型 类 的 值 与 字典 对 象 做 了 映射 。 
像 上 面 这 样 ， 我 们 用 API 提供 数据 模型 的 值 时 ， 必 给 键 和 信 做 好 映射 。 
数据 模型 与 API 啊 应 数据 的 结构 一 致 时 ， 可 以 通过 给 数据 模型 添加 元 信息 的 方式 简化 映射 
的 描述 。 使 用 OR 映射 工具 的 数据 模型 大 多 含有 元 信息 ， 因 此 映射 更 加 简单 一 些 。 但 正如 例子 
所 示 ， 我 们 很 少 能 遇 到 数据 结构 一 致 的 模型 ， 所 以 摘 述 映射 操作 是 必 不 可 少 的 一 步 。 

















15.2.2 ”映射 规则 的 结构 化 与 重复 利用 


在 的 API 时， 意义 相同 部 分 的 映射 代码 要 保持 一 致 ， 以 便 重 复 利 用 。 

LIST 15.10 是 一 个 返回 简单 的 用 户 数据 以 及 留言 数据 ( 包含 用 户 和 文本 的 数据 ) 的 API。 为 
便于 理解 ， ev Web API 的 形式 ， 而 是 直接 在 控制 台 调 用 并 显示 结果 。 男 外 ， 本 例 中 没 
有 使 用 数据 库 。 





© LIST 15.10 mapping model.py 


= coding uti- 


import json 


class User(object): 


cet _—_ Imit (self, icl, PaASSwWOrC, nLEknEne, 


selz icd = icl = eg TD 


self.password = password # 密码 


self.nickname = nickname # 昵称 
self.age = age # 年龄 
class Comment (object): 
gie c imit (self, 1d, user, TEKE) : 


self.id = id d 留言 ID 
self.user = user # ĦF ID 
sel text = twr EE 


cder get user (user she) s 
""" 返回 用 户 对 象 的 函数 
# 实际 开发 时 应 该 访问 数据 库 
user = User (id=user id, 
password-'hoge', 
nickname-'tokibito!, 
age-26) 


Ic NEN user 


deret eccomnenticenneote ou 


'"" 返回 留言 对 象 的 函数 


# 实际 开发 时 应 该 访问 数据 库 


eemmene onem cis conumei te 


user=get_user ('bp12345'), 


text=u'Hello, world!') 


rerturnccommuent 


def mapping user (user): 
"""User 模型 与 API 的 映射 


return ['user id': user.id, 'user nickname': 


def mapping user 2 (user): 
"""User 模型 与 API MERSI 2 


第 15 章 方便 好 用 的 Python 模块 


age): 


user.nickname] 
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"n n II 
return | 'user id': user. id, 
"uger mniLEkname" s, USET, nLECLNanme, 


'user age': user.age] 


eleg mee comment (mmense 
"""Comment 模型 与 API WISI 


return ('user': mapping user(comment.user), 'text': comment .text) 


def apl _ user _ json (user id): 


""" 以 JSON 格式 返回 用 户 数据 的 API 

user = get user(user id) # 获取 User 对 象 

user dict = mapping user(user) 4 映射 到 字典 

return json.dumps(user dict, indent-2) # V JSON ETRE 


lesion scr ams on un 
""" 以 JSON 格式 返回 用 户 详 细 数据 的 API 
user - get user(user id) # Russer? 
user dict = mapping user 2(user) 4 映射 到 字典 
return json.dumps(user dict, indent-2) 4 LDLJSONT&xViR[U] 


dercapisconmeutsysontceemuente d 
""" 以 JSON 格式 返回 留言 数据 的 API 
comment = get comment(comment id) # 获取 Comment HR 
comment dict = mapping comment (comment) # 映射 到 字典 
return json.dumps(comment dict, indent-2) # IX JSON 格式 返回 


def main(): 
# 获取 用 户 数 据 的 JSON 并 显示 
print "--- api user json ---" 


prine ap user Jeon ("igol2345 ") 

# 获取 用 户 数据 ( 详细 ) 的 JSON 并 显示 

printe =-=- epi user detail Co ===" 
prime aol vSer Cercail sons 
# 获取 留言 数据 的 JSON 并 显示 

printe e c &pil Comment Jeon ===" 


printe apl Conmeen Jeon (" ems4321 1) 
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在 这 段 代 码 中 ， 实 现 API DRERI api user json, api user detail json, api comment - 
json。 其 执行 结果 如 LIST 15.11 所 示 。 


E LIST 15.11 执行 结果 


$ python mapping model.py 
=== APL uger Jeon === 
{ 
Se ido copo bus 
iuger nicknames ur 
j 
===- APİ uger Cetail Json ==- 


{ 


US en opis 
uuseekmame oko 
"user @ge": 26 


j 


poems Jeon === 


{ 


Eere"; MHello, wort 
"mM "bpl2545"; 
"user nickname": "tokibito" 

j 

j 

在 api comment json 的 啊 应 中 ，user 部 分 的 数据 结构 要 与 api user json 保持 一 致 ， 因 此 使 
用 了 相同 的 映射 晒 数 。 相 对 地 ， 虽 然 api user detail json 与 api user json 的 结构 大 致 相同 ， 但 
它们 具有 差异 的 部 分 使 得 它们 用 了 不 同 的 映射 晒 数 。 

像 上 面 这 样 ， 由 于 每 个 API 之 间 都 只 存在 细微 的 差异 ， 使 得 映射 函数 成 了 一 个 俄罗斯 套 娃 
般 的 结构 。 随 着 这 种 函数 增多 ， 代 码 的 可 读 性 会 越 来 越 差 。 另 外 ， 因 API 的 需求 变更 而 导致 函 
数 传 值 参数 增加 时 ， 需 要 一 次 性 修正 多 个 地 方 。 

这 些 问题 可 以 通过 导入 bpmappers 来 解决 。 














15.2.3 导入 bpmappers 





bpmappers 能 帮助 我 们 将 对 象 或 字典 的 数据 映射 到 其 他 字典 上 。bpmappers 通过 pip 命令 进 
fü, ARASAN LIST 15.12 所 示 。 本 书 使 用 的 bpmappers 版 本 是 0.8。 
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© LIST 15.12 用 pip 命令 安装 bpmappers 


$ pip install bpmappers 


bpmappers 主要 由 Mapper 类 和 Field 类 构成 。Mapper ZSTH25-T BRI PAZ, Field 类 相当 于 映 
射 字 骨 的 键 值 对 。 我 们 通过 Python shell 执行 bpmappers ， 做 一 个 简单 的 映射 ( LIST 15.13 )。 


加 LIST 15.13 用 bpmappers 做 映射 


>>> from bpmappers import Mapper, RawField 
>>> class SpamMapper (Mapper): 
spam = RawField('foo!) 


egg = RawField('bar!') 


»»» SpamMapper (dict(foo-123, bar-'abc')).as dict() 
('egg': 'abc', 'spam': 123) 
例子 中 定义 了 继承 Mapper 类 的 SpamMapper 类 ， 其 属性 包含 spam 和 egg 两 个 RawField 对 
象 。 生 成 SpamMapper 类 的 实例 时 ， 传 值 参数 中 指定 了 用 做 映射 对 象 的 宇明 。 映 射 后 的 字 旺 可 
以 通过 执行 Mapper 类 的 as. dict MARIA. SpamMapper 类 将 foo 键 (或 属性 ) 的 值 映 射 到 了 
spam 键 ， 将 bar 键 (或 属性 ) 的 值 映 射 到 了 egg 键 。 
接 下 来 我 们 对 前 面 那个 返回 用 户 数 据 和 留言 数据 的 API ( mapping model.py ) 的 源码 作 一 下 
修改 ， 对 其 导入 bpmappers。 类 和 图 数 的 重复 部 分 在 此 省 略 。 








加 LIST 15.14 bpmappers mapping model.py 


u Coding: WEE=8 
import json 


from bpmappers import Mapper, RawField, DelegateField 


class User (object): 


" B " 


class Comment (object): 


" 省 略 " 


det get user (user heb s 


" B " 


def get comment (comment id): 


" 省 略 " 


class UserMapper (Mapper): 
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"""User 模型 与 API 的 映射 


user icl = RawPLelel( "icl" ) 


user nickname Rav Eek nickname" ) 


class UserMapper2 (UserMapper): 


"""User 模型 与 API 的 映射 2 


user age = RawField('age') 


class CommentMapper (Mapper): 


def 


def 


def 


def 


"i" Comment 模型 与 API 的 映射 


user 


DelegateField (UserMapper) 


text RawField() 


api user json(user id): 

""" 以 JSON 格式 返回 用 户 数 据 的 API 

user - get user(user id) s oer 

user dict = UserMapper(user).as dict() 4 映射 到 字典 
return json.dumps(user dict, indent-2) # D JSON {8 TUR El 


api user Cetail Jeon luser el) s 

""" 以 JSON 格式 返回 用 户 详细 数据 的 API 

user - get user(user id) s kB User Xs 

user dict = UserMapper2(user).as dict() 4 映射 到 字典 
return json. dumps (user dict, indent-2) # D JSONTf&xVi&Iul 


api comment | exer (comment id): 


""" 以 JSON 格式 返回 留言 数据 的 API 


comment = get comment(comment id) # 获取 Comment WZ 


方便 好 用 的 Python 模块 


comment dict = CommentMapper(comment).as dict() 4 映射 到 字典 


return json.dumps(comment dict, indent-2) # DI JSON {K TRE] 
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LIST 15.14 的 执行 结果 没有 变化 。api user json 使 用 了 UserMapper。api user detail json 使 
用 的 是 继承 UserMapper HJN Y age 映射 的 UserMapper2 类 。 可 以 看 到 ，bpmappers 的 Mapper 
类 能 够 利用 继承 的 结构 来 添加 不 同 的 映射 。 另 外 ，api_comment json 的 user 部 分 与 UserMapper 
的 数据 结构 相同 ， 所 以 我 们 直接 通过 DelegateField 指定 了 UserMapper。 这 种 俄罗斯 套 娃 式 的 映 
射 结构 同样 可 以 用 其 他 类 来 实现 。 

另外 ， 列 表 内 元 素 的 套 娃 式 映射 可 以 用 ListDelegateField 来 完成 。LIST 15.15 中 ， 我 们 通过 
Python shell 执行 了 一 个 用 ListDelegateField 实现 的 映射 。 














© LIST 15.15 用 ListDelegateField 实现 的 映射 


>>> from bpmappers import Mapper, RawField, ListDelegateField 
>>> class SpamMapper (Mapper): 


Spam = RawField('foo!) 


>>> class ListSpamMapper (Mapper): 
spam list = ListDelegateField (SpamMapper) 


= iSt o pamMapper (l spam Pisti oos ("too A456 aa dict) 
Cepam lisri: I spa 1120 spam So 
ListDelegateField 中 指定 了 继承 Mapper 类 的 SpamMapper 2$, ListDelegateField 可 以 以 指定 
的 类 映射 列表 中 的 各 个 元 素 。 通 过 上 述 例子 我 们 可 以 看 到 ， 用 bpmappers PEW fij 4 eT XE X , 
同时 方便 映射 的 重复 利用 。 








15.2.4 与 Django 联动 


bpmappers 的 一 些 功 能 可 以 为 Django 框架 的 模型 对 象 映射 提供 辅助 。 使 用 bpmappers. 
djangomodel.ModelMapper 可 以 轻松 地 根据 Django 的 模型 类 生成 用 于 映射 的 类 。 

下 面 我 们 用 ModelMapper 类 来 给 人 简单 的 Django 模型 类 作 一 个 映射 。 请 注意 ， 这 里 我 们 不 创 
Œ Django 工程 ， 所 以 需要 在 源码 内 初始 化 Django(LIST 15.16 )。 





© LIST 15.16 django and bpmappers.py 
"ecosun uis 
# 初始 化 Django 
from django.conf import settings 


settings.configure() 


from django.db import models 


from bpmappers.djangomodel import ModelMapper 
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class Person(models.Model): 


"n" 表示 人 的 数据 模型 


name = models.CharField(u' %47 ', max length-20) 
age = models.IntegerField(u' 年 龄 ') 


class Meta: 
# 指定 app_labe1， 防 止 应 用 名 解析 时 出 错 
apo label = cu 


class PersonMapper (ModelMapper): 
"""iF Person 模型 映射 到 字典 时 需要 用 到 的 类 


class Meta: 


model = Person 


def main(): 
# 生成 Person 对 象 
person = Person(id-123, name-u'okano', age-26) 
# 映射 到 字典 
Essence PernseonMaen( er on sie 
# 输出 到 屏幕 上 


print person e 


if | name == ' main ': 
main() 

为 了 让 Person 模型 映射 到 字典， 我 们 定义 了 一 个 继承 ModelMapper 类 的 PersonMapper 类 。 
ModelMapper 2$ Ky iE X f V Sp 2$ Meta, model 18 4E f Person Bi 7B, ix FF A XI Jn. 
ModelMapper WA A 2/4 f Person 模型 拥有 的 字段 生成 映射 。 

在 安装 了 bpmappers 和 Django 的 计算 机 上 运行 上 述 代 码 将 得 到 如 LIST 15.17 所 示 的 结果 。 








E LIST 15.17 执行 结果 


$ python django and bpmappers .py 


['id': 123, 'name': u'okano', 'age': 26) 


15.2.5 编写 JSON API 
接 下 来 我 们 在 导入 bpmappers 的 前 提 下 实际 编写 一 个 返回 JSON 格式 啊 应 的 API。 首 先 ， 我 
们 以 第 2 草 中 开发 的 留言 板 应 用 为 例 编写 代码 ， 实 现在 用 户 提 交 信 息 时 以 JSON 格式 返回 啊 应 。 
具体 代码 如 下 。 
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from flask import jsonify 


from bpmappers import Mapper, RawField, ListDelegateField 


class GreetingMapper (Mapper): 
name - RawField() 


comment = RawField() 


class GreetingListMapper (Mapper): 
greeting list = ListDelegateField (GreetingMapper) 


@application.route('/api/') 
cder apil ince dg 
Jungs esr 
# 读 取 提交 的 数据 
greeting list = loac catal() 
resulte Cier = GreetingListMappoer | 
('greeting list': greeting list]).as dict() 
& 以 JSON 格式 返回 响应 


return jsonify(**result dict) 

将 这 段 代 码 添加 到 guestbook.py HJ if name  - Bi. JSON 的 啊 应 会 以 greeting list 
为 键 ， 通 过 数组 的 形式 返回 各 次 提交 的 姓名 以 及 留言 内 容 。 要 返回 的 数据 通过 已 有 的 load_data 
PR X 3X NX, SA Jn LA GreetingListMapper 类 进行 映射 。GreetingListMapper 类 使 用 了 
ListDelegateField 类 ， 从 而 实现 以 GreetingMapper 类 对 列表 内 的 值 进 行 映射 。 

接 下 来 保存 修改 ， 执 行 源码 并 局 动 服务 入。 在 添加 儿 条 数据 之 后 访问 http:// 
127.0.0.1:5000/api/, 我们 会 得 到 JSON 格式 的 响应 。 下 面 是 用 urllib 访问 时 的 例子 。 








Sept: omesmuusddu bet tp /27.0.0.155000/ 5015 / 


{ 


greeting lists qr 


{ 


"comment": "\u65e5\u672c\u8a9e\u306e\u6587\u5b57\u5217", 
namen cto to: t 

E 

í 
"comment": "Hello, world!", 


inemes tco ba te 
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导入 bpmappers 能 提高 映射 的 重复 利用 率 ， 还 能 让 我 们 在 需求 变更 时 更 灵活 地 加 以 应 对 ， 
因此 即便 是 很 简单 的 API， 也 建议 用 bpmappers 来 实现 。 





15.3 ”图 像 处 理 


Python 的 图 像 处 理 通 常用 Pillow ( Python Imaging Library ( Fork )) 来 进行 。Pillow 由 PIL 
( Python Imaging Library ) 的 分 支 工 程 开 发 而 来 。 由 于 PIL 已 经 停止 开发 及 维护 ， 所 以 如 今 
Pillow 成 为 了 主流 。 它 文 持 JPEG、PNG、GIF、BMP 等 多 种 图 像 格式 。 本 书 使 用 的 是 Pillow 的 
2.6.1 版 本 。 


Pillow 
http://pillow.readthedocs.org/ 


15.3.4 X Pillow 


Pillow 与 多 种 处 理 图 像 数 据 的 程序 库存 在 依赖 关系 ， 因 此 安装 时 和 需要 多 加 注意 。 目 前 Pillow 
在 PyPI 上 提供 了 面向 Windows 和 OSX 义 的 wheel 包 。 在 Windows、OS X 上 安装 (包括 用 pip 命 
SER ) 时 不 需要 进行 编译 。 如 采 使 用 的 是 其 他 平台 ， 那 么 由 于 需要 从 sdist 进行 C 扩展 的 编 
译 ， 所 以 必须 准备 编译 占 和 各 种 图 像 处 理 库 。 























€ & wheel 可 用 的 平台 
如 果 是 OS X 和 Windows， 只 需 像 LIST 15.18 这 样 使 用 pip install 安装 wheel 包 即 可 。 


© LIST 15.18 Æ OSX E Pillow 


$ pio necall dil1lew==2.6.1 
Downloading/unpacking pillow==2.6.1 

Dowmmloacine PLLlow-2.6,.1l-69p27-nE0ne-macosx 10 6 intel macosx 10 Me 
macosx 10 9 x86 64.whl (2.8MB): 2.8MB downloaded d 
Installing collected packages: pillow 
Successfully installed pillow 


Cleaning up... 


€ 从 源码 构建 
接 下 来 准备 进行 Pillow 编译 时 所 需 的 库 。 下 面 以 Ubuntu 14.04 为 例 进 行 学 习 。 
自 完 ， 因 为 需要 编 详 C 扩 展 ， 所 以 需要 一 些 基本 的 开发 工具 。 我 们 先 来 确认 一 下 1.1 节 中 
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的 安装 ( LIST 15.19 )。 


© LIST 15.19 检查 设置 以 便 进行 python 的 C 扩展 编译 


$ Doe=Confilg Dytnon-=2.7 -==1158 -=-erlagg 
-I/usr/include/python2.7 -I/usr/include/x86 64-linux-gnu/python2.7  -lpython2.7 


男 外 ， 图 像 格 式 和 字体 等 的 支持 需要 用 到 下 述 程序 库 。 





支持 对 象 库 
JPEG libjpeg-dev 





OpenJPEG libopenjpeg-dev 


zlib1g-dev 





libtiff5-dev 


libwebp-dev 





libfreetype6-dev 





libBlIcms2-dev 








执行 LIST 15.20 中 的 命令 ， 统 一 安装 Pillow 需要 的 程序 包 。 


E3 LIST 15.20 E Pillow 需要 的 程序 包 


$ sudo apt-get install libjpeg-dev libopenjpeg-dev zliblg-dev libtiff5-dev d 
libfreetype6-dev libwebp-dev liblcms2-dev 





现在 所 需 工 具 和 库 已 经 齐全 ， 可 以 用 pip 进行 安装 了 (LIST 15.21) 


© LIST 15.21 用 pip 命令 安装 Pillow 


$ pip install pidbow--2 6c 





CRNS os ARIA. RIEKER PZW EnA., LIST 15.22 
是 除 TKINTER 以 外 的 所 有 功能 均 生 效 的 例子 。 


© LIST 15.22 ”查看 支持 的 功能 


Te el la Cl Ee 


version Pg llow 2-6.1 
pce om linu? 2.76 (detault, Mar 22 2014, 22:59:56) 
[GCC 4.8.2] 


*** TKINTER support not available 
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--- JPEG support available 

--- OPENJPEG (JPEG2000) support available (2.1.3) 
--- ZLIB (PNG/ZIP) support available 

--- LIBTIFF support available 

BSSSMEREERYPHOIE SUpport evailable 

--- LITTLECMS2 support available 

--- WEBP support available 

--- WEBPMUX support available 


To check the build, run the selftest.py script. 


NOTE 

Pillow 2.6.1 无 法 识别 Ubuntu 14.04 上 安装 的 libopenjpeg-dev。 今后 的 版 本 中 应 该 会 修复 
这 个 问题 。 

如 果 应 用 不 涉及 Tkinter 模块 的 图 像 ， 可 以 不 用 管 TKINTER 的 支持 问题 。 另 外 ， 安 装 
Python 时 ， 如 果 Tkinter 模块 并 未 生效 ， 同 样 无 法 支持 TKINTER。 


15.3.2 图像 格式 转换 


图 像 文件 的 格式 转换 通过 在 Image 类 的 save 方法 的 传 值 参数 中 指定 格式 并 保存 来 完成 。 下 
面 ， 我 们 打开 当前 目录 下 名 为 python.gif 的 图 像 文 件 ， 将 其 转换 为 JPEG 格式 ， 并 保存 在 
python convert.jpg 文件 中 。 具 体 代码 如 下 。 











= coding: ee 


from PIL import Image 


def main(): 
# 打开 文件 获取 Image X 
image = Image.open('python.gif') 
# 模式 转换 为 RGB 
image rgo = image. Convert | eb 


# 图 像 保存 至 文件 


image rgo. save ("python Convert. Jeg", "Jpeg" ) 
it o neme _ == moie 
main () 


可 以 看 到 ， 程 序 在 读 取 完 文件 之 后 将 图 像 模式 转 为 了 RGB。 
在 GIF 以 及 不 足 256 色 的 PNG、BMP 等 格式 中 ， 颜 色 信 息 都 保存 在 调 色 板 数 据 块 里 。 这 
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类 文件 用 Pillow 打开 时 分 为 了 模式 ( 调 色 板 模式 ) 和 1 模式 ( 单 色 模 式 )。 男 外 ，JPEG 文件 有 
时 还 会 是 CMYK 模式 。 当 模式 不 支持 save 方法 指定 的 格式 时 ， 程 序 会 报错 ， 所 以 要 先 用 
convert 方法 进行 模式 转换 。 





15.3.3 ”改变 图 像 尺寸 


如 果 想 改变 图 像 尺 寸 ， 可 以 使 用 Image 类 的 thumbnail 方法 或 resize 方法 。 下 面 ， 我 们 打开 
当前 目录 下 名 为 python.jpg 的 图 像 文 件 ， 将 其 长 宽 缩 小 一 半 后 保存 为 python thumbnail.jpg, fV 
人 码 如 LIST 15.23 所 示 。 





© LIST 15.23 pil thumbnail.py 


4 coding: utf-8 


from PIL import Image 


def main(): 
# 打开 文件 获取 Image 对 象 
image = Image.open('python.Jjpg') 
&OYDEEMCKGEBS— F 
half size = (image.size[0] / 2, image.size[1] / 2) 
# 图 像 大 小 降 为 一 半 
image.thumbnail(half size, Image.ANTIALIAS) 
# 图 像 保存 至 文件 
Image.Save('DPYthon thumbnail.jpg') 


if | name  -- ' main  ': 
main () 

Image 类 的 对 象 能 够 通过 size 属性 以 元 组 的 形式 获取 图 像 的 长 和 宽 。 

thumbanil 方法 的 第 一 个 传 什 参数 指定 了 网 像 长 和 宽 的 元 组 ， 第 二 个 传 信 参数 指定 了 滤 镜 
Image.ANTIALIAS。 滤 镜 有 NEAREST、BILINER、BICUBIC、ANTIALIAS4 种 可 供 选 择 ， 其 
中 使 用 ANTIALIAS 修改 尺寸 后 的 图 像 品 质 最 高 ( 损失 最 小 )。 

在 执行 thumbnail 方法 之 后 ， 会 直接 修改 对 象 目 身 的 图 像 大 小 。 但 是 ， 这 个 方法 只 能 用 于 长 
宽 比 例 不 变 的 修改 。 变 更 长 宽 比 例 时 需要 使 用 resize 方 法。 下 面 ， 我 们 打开 当前 目录 下 名 为 
python.jpg 的 图 像 文件 ， 将 其 长 度 放 大 为 2 倍 后 保存 为 python _ resize.jpg， 具 体 代 码 如 LIST 
15.24 所 示 。 














© LIST 15.24 pil_resize.py 


u Coding: er 


from PIL import Image 
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def main(): 
# 打开 文件 获取 Image 对 象 
image = Image.open('python.jpg!') 
# 计算 图 像 长 度 的 2 5 
double size = (image. sizelOl, image- sizelil] = 2) 
# 图 像 大 小 增加 至 2f 
image _ resized = image.resize (double size, Image.ANTIALIAS) 
# 图 像 保存 至 文件 


iunaecaenesi cse Sove CP Nenin eo 


it E neme _— =s man 


main () 


与 thumbnail 7; 1E ^ fF], resize 方法 的 返回 值 是 修改 尺寸 后 的 Image 类 的 对 象 。 它 同 
thumbnail 一 样 ， 可 以 指定 滤 镜 。 图 15.1 和 图 15.2 分 别 是 修改 尺寸 之 前 的 图 像 与 执行 完 LIST 
15.24 所 示 的 代码 之 后 的 图 像 。 


ython 


15.1 修改 尺寸 之 前 的 图 像 (python.jpg ) 











15.2 ”修改 尺寸 之 后 的 图 像 ( python_resize.jpg ) 
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15.3.4 “剪裁 图 像 


Image 类 的 crop 方法 能 够 以 长 方形 剪裁 图 像 。 下 面 ， 我 们 打开 当前 目录 下 名 为 python.jpg 
的 图 像 文 件 ， 按 照 图 像 的 宽度 从 正中 间 剪 裁 一 个 正方 形 并 保存 为 python_crop.jpg。 





© LIST 15.25 pil crop.py 
4 coding: utf-8 


from PIL import Image 


def main(): 
# 打开 文件 获取 Image 对 象 
image = Image.open('python.Jjpg') 
# 根据 短 边 长 度 求 中 央 正 方形 的 坐标 
if image.size[0] < image.size[1]: 
# 横 边 较 短 时 ( 瘦 高 的 图 像 ) 
crop rect = ( 
0, 
(image.size[1] - image.size[01) / 2, 
image.size[0], 
(image.size[1] - image.size[0]) / 2 + image.size[0]1) 
elses 
# 坚 边 较 短 时 ( 矮 胖 的 图 像 ) 
GE rect 三 
(image.size[0] - image.size[1]) / 2, 
0, 
(image.size[0] - image.size[1]) / 2 + image.size[1]l, 
image.size[1]) 
H BUE 
image Cropped = image. Crop Mc ed 
# 图 像 保存 至 文件 


image Cropped. save ("python erop. Jpg") 


lt o name _— == | marin ': 


main () 





crop 方法 的 传 值 参 数 是 包含 4 个 值 的 元 组 ( Tuple), ix 4 个 值 代 表 长 方形 剪裁 区 域 的 左上 
角 坐 标 和 右 下 角 坐 标 。crop MREMEN AA SIR KURAI Image 类 对 象 。 执 行 LIST 15.25 中 的 
代码 后 会 得 到 如 图 15.3 所 示 的 结 





第 15 章 方便 好 用 的 Python 模块 | 375 


fth 


15.3” 勇 裁 后 的 图 像 ( python. crop.jpg ) 


15.3.5 ”对 图 像 进行 滤 弹 处 理 


进行 滤 镜 处 理 必须 获取 像素 值 。 像 素 值 可 以 用 Image 类 的 getdata 方法 或 getpixel 方法 来 获取 。 
获取 的 像素 值 为 包含 R( 红 ) GC) 、B( 蓝 )3 个 值 的 元 组 ， 3 个 值 的 范围 均 为 0 ~ 255。 下 面 ， 
我 们 打开 当前 日 录 下 名 为 python.jpg 的 图 像 文 件 ， 将 所 有 像 床 反 色 并 保存 为 python filterjpg。 


回 LIST 15.26 pil_filter.py 


= Coding: uti-8 


from PIL import Image 


def main(): 
# 打开 文件 获取 Image X 
image = Image.open('python.jpg!') 
buffer = [] 
# 循环 逐一 获取 图 像 的 像素 
for pixel in image.getdata(): 
# 将 像素 反 色 并 存 六 组 部 区 
buffer.append(( 
255 - pixel[0], 
255 ~- pixeli], 
255 - pixel [2])) 
# AZOTA A h2 S SUR Sus 
image.putdata (buffer) 
# 图 像 保存 至 文件 
image. save ("python ELLter, Jpg") 


it EE On MEE '"_ main  ': 
main () 
getdata 7r ikfBEWeux n] —NERR a, HFE RRE — HRR E. TEL, RIZ 
一 取出 了 每 个 像素 的 像素 值 并 进行 反 色 (255 减 去 色 值 )。 等 所 有 像素 值 处 理 完毕 之 后 ， 用 
putdata TARM Y Image ŽI RIRE LIST 15.26 的 执行 结果 如 图 15.4。 
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15.4 反 色 后 的 图 像 ( python_fiter.jpg ) 








如 果 要 获取 指定 坐标 的 像素 值 ， 可 以 用 Image 类 的 getpixel 方法 。 下 面 ， 我 们 打开 当前 目 
录 下 名 为 python.jpg 的 图 像 文件 ， 将 右上 角 的 像素 反 色 并 保存 为 python_ pixel.jpg， 有 具体 代码 如 
LIST 15.27 所 示 。 


© LIST 15.27 pil pixel.py 


# coding: utf-8 


from PIL import Image 


def main (): 
# 打开 文件 获取 Image 对 象 
image = Image.open('python.Jjpg!') 
# 右上 角 的 位 置 


point = (image.size[0] - 1, 0) 
# 获取 像素 值 
pixel = image.getpixel (point) 


# 改写 为 反 色 的 像素 值 
image.putpixel(point, ( 
255 - pixel[0], 
255 - pixel[1], 
255 - pixel[2])) 
# 图 像 保存 至 文件 
image. save | ey on 


if o name =a | marin ': 


main() 





getpixel 方法 的 传 值 参 数 为 含有 横 纵 坐标 (起 点 为 0 ) 两 个 值 的 元 组 。 改 写 指定 位 置 像 素 值 
时 使 用 了 putpixel 方 法。 这 些 方法 的 方便 之 处 在 于 能 够 指定 坐标 ， 但 是 速度 太 慢 ， 因 此 一 旦 需 
要 大 量 使 用 ， 它 们 的 效率 并 不 见得 比 getdata, putdata 等 方法 更 高 。 
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15.4 数据 加 密 





在 数据 传输 过 程 中 ， 为 防止 数据 被 第 三 方 获 取 或 贷 改 ， 需 要 对 数据 进行 加 密 。 这 里 我 们 学 
习 一 下 如 何 通 过 PyCrypto 进行 通用 加 密 系 统 和 公 钥 加 密 系 统 的 加 密 及 解密 。 





PyCrypto 








https://pypi.python.org/pypi/pycrypto 





15.4.1 3€ PyCrypto 
lli LIST 15.28 Brzk , PyCrypto 的 安装 可 以 通过 pip 合 令 进行 。 由 于 它 包含 C 语言 编写 的 模 
块 ， 所 以 安装 时 与 Pillow 一 样 需要 gcc 等 编译 需 。 各 位 可 以 事先 用 apt 安装 python-dev 包 和 
build-essential 包 。 本 书 使 用 的 是 PyCrypto 的 2.6.1 版 本 。 





EJ LIST 15.28 用 pip 命令 安装 PyCrypto 


$ pip tastall wertESc==2.6.1 


15.4.2 通用 加 密 系 统 的 加 密 及 解密 


通用 加 密 系统 在 加 密 和 人 解密 时 使 用 同一 僚 密 钥 。AES、DES 等 都 属于 通用 加 密 算 法 。AES 
Hye RAI BERURKSPESIT DES， 因 此 安全 性 较 高 。 本 书 使 用 的 就 是 AES. 





NOTE 
DES ( Data Encryption Standard ) 是 1977 年 被 美国 标准 化 的 加 密 系统 。 
AES ( Advanced Encryption Standard ) 是 2011 年 被 美国 标准 化 的 加 密 系 统 。 


以 AES 加 密 、 解 密 时 需要 用 到 PyCrypto 的 Crypto.Cipher.AES 类 。 下 面 我 们 用 PyCrypto 实 
现 AES 加 密 及 解密 ， 并 将 结果 输出 到 屏 硕 上 (LIST 15.29 )。 





© LIST 15.29 aes encrypt.py 


= Coding: ee 
from Crypto.Cupher smport AES 


KEY = 'testtesttesttest' # 加 密 和 解密 时 使 用 的 通用 密 钥 
DATA = '0123456789123456' # 数据 长 度 为 16 的 倍数 
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def main(): 
aes = AES.new(KEY) # ÆR AES 类 的 实例 
encrypt data = aes.encrypt(DATA) # Ju 
print repr(encrypt data) # ih £ PFa 
decrypt data = aes .decrypt (encrypt data) # 解密 
print repr(decrypt data) 4 dauu25m 


if name == ' maim  ': 


main() 








给 AES.new 函数 指定 用 作 密 钥 的 字符 串 ， 生 成 AES 对 象 。 密 钥 可 以 是 长 度 为 16、24、32 
字符 的 任意 字符 串 。 数 据 通 过 AES 对 象 的 encrypt 方法 加 密 ， 通 过 decrypt 方法 解密 。 上 述 代 码 
段 的 执行 结果 如 LIST 15.30 所 示 。 





e LIST 15.30 ”执行 结果 


$ python aes.py 
IAEA IN sülexc eese f occi eee dO zf ROOT 
"0123456789123456! 





执行 结 末 的 第 一 条 输出 是 加 密 状 态 的 数据 ， 第 二 条 是 将 加 密 的 二 进 制 串 解密 后 还 原 的 数据 。 


15.4.8 AAWE RA ( RSA ) 的 加 密 与 解密 
公 钥 加密 系统 在 加 密 和 解密 时 分 别 使 用 不 同 的 密 钥 。RSA 等 就 是 公 钥 加 密 算 法 。 








NOTE 


RSA 是 Ron Rivest, Adi Shamir, Len Adleman F 1977 年 发 明 的 加 密 算法 。 


€ RSA 私 钥 和 公 铀 的 生成 

在 公 角 加密 系统 中 ， 加 密使 用 公 钥 ( Public key )， 解 密使 用 私 钥 ( Private key). ix VARIUS 2] 
都 需要 通过 算法 生成 。 公 钥 和 私 钥 的 密 钥 对 可 以 通过 ssh-keygen 命令 或 openss1l 命令 来 创 
建 ， 不 过 我 们 这 里 要 学 习 的 是 用 PyCrypto 生成 密 钥 的 方法 。 下 面 ， 我们 用 PyCrypto 生成 RSA 
的 密 钥 对 ， 以 PEM 格式 ( RFC1421 ) 输出 到 屏幕 上 ， 具 体 代码 如 下 。 











© LIST 15.31 rsa generate keypair.py 
# coding: utf-8 
from Crypto.PublicKey import RSA 


crom Crypto ee Rancom 
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INPUT SIZE = 1024 


def main(): 


random func = Random.new().read # 产生 随机 数 的 函数 

key pair = RSA.generate(INPUT SIZE, random func) 4 生成 密 钥 对 
private pem = key pair.exportKey() 4 获取 PEM 格式 的 私 角 

public pem = key pair.publickey().exportKey() # IRE PEM 格式 的 公 钥 
print private pem 4 ADERS 

print public pem 4 输出 至 屏幕 
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LIST 15.31 用 RSA.generate 函数 生成 了 RSA 密 钥 对 的 对 象 ， 用 exportKey 方法 获取 了 用 作 


私 钥 的 PEM 格式 的 字符 串 。 公 钥 则 是 先 通过 publickey 方法 获取 对 象 ， 然 后 再 用 exportKey 77 
法 获取 的 。 上 述 代码 的 执行 结果 如 LIST 15.32 所 示 。 


E LIST 15.32 执行 结果 


$ python rsa generate keypair.py 


MIICXgIBAAKBgQDMYS23401C1Z2fbeZazcUnEfspBcsO6hSmvDji-Jm5Gk6tvIHl 


IFFulaCD8kBbjf2ivzmG8Dgtcn6jnLjXe3EBOHlvh70TUsvi0ZjxZsmbv6fJmJrQ 


ZJvW1Wi3wnoBeVYOk6ha8rbfY35wErxxdTWeWml1nSBwaFfnRFYnrkqVGlQIDAQAB 


AoGBAKJZ39Ne6A/bWOa4inA/XQl4QyeHLrDN8bGxew7xpEtiFnXOdMrqLUX59RRb 


b7xKwtxxQuVqFXYkqWyWpk6mBFGCcRH1yH888Cgu«mSbsKvMAGOW/OoT17XLV8hc4T 


mOiT/gEUsCHFcE6mstkUIEMlZCWmnuoijprDbehhlOSEZPQBAkEAlIFgXqMGIC/x 


CYwrizFgJVAa/oAIF183CocfqPaYlotKCeNovnPXeSCmAX1dOGhCHKBIQmkmL7YU 


TZIDxiWLl1QJBAPY2CWyA26GKGulWzURJa7guizaqGJpghF30U5VdvdKmetYU2gXA 


rhHQ9LxdjGO9L9BWSxg5Y1Z102b8f2Qf78ECQOCNr3VBpBCBhXWAmCSwOCURFUfq 


UWizrJhWPKGvVjuGpHhI/4bm9PXFnS8R7zSNr/XkgDmtjc4YIZ6HAUM-«-6enBAkBi 


yC9jvxdfan9/NdJJUYPMC7AbEIeqeIri/OIBrYiZWX3zIo6OvE2ajFGEuau7sE7Cc 


SaKTZAL5iQUWTrvlufKBAkEAis4KsIA4InxzOlZPRcmPlUVKULvVqyquqsfKP-«NFG 


PTurYiXOC2kXPbBNxyhTDQ6Dw3OBOGhARHSGiuhQQicA2w-- 


MIGfMAOGCSqGSIb3DQEBAQUAAAGNADCBiQKBgQDMYS23401C1Z2fbeZazcUnEfsp 


Bcs06hSmvDji-Jm5Gk6tvlIHlIFFulaCD8kBbjf2ivzmG8Dgtcn6jnLjXe3EBOHlv 


h70TUsvi0OZjxZsmbv6efJmJrQzJvW1Wi3wnoBeVYQke6eha8rbfY35wErxxdTWeWmln 


SBwaFfnRFYnrkqVGlQIDAQAB 


在 输出 的 字符 串 中 ， 从 ----- BEGIN RSA PRIVATE KEY----- 到 ----- 
---- 的 部 分 为 私 钥 ， 从 ----- BEGIN PUBLIC KEY----- P| aai END PUBLIC KEY----- 
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的 部 分 为 公 钥 。 加 密 解 密 时 就 是 使 用 这 一 对 密 钥 。 


€ Fi SB In 
加 密 需 要 使 用 公 钥 。PyCrypto 可 以 使 用 我 们 输入 的 PEM ERAH, PIE. RTS 
字符 种 Hello, world! 加 密 并 输出 到 屏幕 上 (LIST 15.33 )。 


© LIST 15.33 rsa_encrypt.py 


# coding: utf-8 
from Crypto.PublicKey import RSA 


from Crypto import Random 


DAME- 'Hello, wocld!! 

EUPIPOA RB YD RN e BECHNEPRUBITICHKE NS 
MIGfMAOGCSqGSIb3DQEBAQUAAAGNADCBiQKBgQDMYS23401C1Z2fbeZazcUnEfsp 
Bcs06hSmvDji«c-Jm5Gk6tvIHlIFFulaCD8kBbjf2ivzmG8Dgtcn6jnLjXe3EBOHlv 
h70TUSsviOZjxZzsmbv6fJUmJrQzJvWl1Wi3wnoBeVYQk6ha8rbfY35wErxxdTWeWmln 
SBwaFfnRFYnrkqVGlQIDAQAB 

二 一 一 一 一 ENDEEPEVUEMICERKEN LL 


def main(): 
random func = Random.new().read # 产生 随机 数 的 函数 
public key = RSA.importKey(PUBLIC KEY PEM) # 输入 PEM 格式 的 公 争 
encrypted = public key.encrypt(DATA, random func) 4 JIS Xj 
print encrypted 4 输出 至 屏幕 


if name == ' maim  ': 


main() 


这 段 代 码 用 RSA.importKey 因数 输入 公 角 并 获取 了 RSA 对象， 然后 用 encrypt 方法 进行 加 
密 。encrypt 方 法 的 传 值 参数 处 指定 了 需要 加 密 的 数据 以 及 产生 随机 数 的 函数 。 上 述 代码 的 执行 
结果 如 LIST 15.34 所 示 。 


E LIST 15.34 ”执行 结果 


$ python rea encrypt 9y 

('NXO5 a\\\xboU\x88/El\xla\x02\xe6\xb4\xede\xf2\xe6\xe3\xa6&~\x9e\x180[K%i\x02k 
Noxdciboxels sooo goce cies SENSOR TEADS EET ON 9B 
x00*qWXxceNxacANx9aNxe3$] \xe5*\x9e\x91F\xd2\xe3P\xb8+\xa6\xc1R\xde\xf2G\xf1\x185\ 
xcd\x8f\x82\xla\xa4c\xf5\x9c\xd8\xe0\xdig \xfdw\xa0\xe6\xca\xf7\x9f\xde\xbf (\xa 
2\xd5\xdb\xd5}\xe5\xaf\x99\xf9\x90\xlcx\n\xe8\xda\x14\x9cJ\xd7\xe4\x96S',) 
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€ 用 私 钥 解密 
解密 需要 使 用 私 钥 。 与 加 密 时 一 样 ， 这 里 也 要 输入 PEM 格式 的 字符 串 。 下 面 ， 我 们 把 前 面 
加 密 的 数据 解密 并 显示 在 屏 芭 上 ， 代 码 如 LIST 15.35 所 示 。 














© LIST 15.35 rsa_decrypt.py 


us Coding, uti-8 
from Crypto.PublicKey import RSA 


DATA = ('\x05 a\\\xb9U\x88/E1\xla\x02\xe6\xb4\xede\xf2\xe6\xe3\xa6&~\x9e\x180 [K 
eui xd dbsseEdi la eocca ONe oou vec R8 oe) glos 7 oeba voco IL\X80\xe 
9NxX83Xx00*qVxceNxacANx9aNxe3$] \xe5*\x9e\x91F\xd2\xe3P\xb8+\xa6\xc1R\xde\xf2G\xf1 
\x185\xcd\x8f\x82\xla\xa4c\xf5\x9c\xd8\xe0\xdlg \xfdw\xa0\xe6\xca\xf7\x9f\xdexbf 
(\xa2\xd5\xdb\xd5 }\xe5\xaf\x99\xf9\x90\xlcx\n\xe8\xda\x1l4\x9cJ\xd7\xe4\x96S',) 
PRIVATE KEY PEM 9e "Wc BROTINOROZOPRIEVATBOINEY--—-—— 
MIICXgIBAAKBgQDMYS23401C1Z2fbeZazcUnEfspBcs0O6hSmvDji-Jm5Gk6tvIHl 
IFFulaCD8kBbjf2ivzmG8Dgtcn6jnLjXe3EBOHlvh70TUsvi0ZjxZsmbv6fJmJrQ 
ZzJvW1Wi3wnoBeVYOQk6ha8rbfY35wErxxdTWeWmlnSBwaFfnRFYnrkqVGlQIDAQAB 
AoGBAKJZ39Ne6A/bWOa4inA/XQl4QyeHLrDN8bGxew7xpEtiFnXOdMrqLUX59RRb 
b7xKwtxxQuVqFXYkqWyWpk6mBFGCRH1yH888Cgu«mSbsKvMAGOW/OoT17XLV8hc4T 
mOiT/gEUsCHFcE6mstkUIEMIlZCWmnuoijprDbehhlOSEZPQBAkEAl1IFgXqMGIC/x 
CYwrizFgJVAa/OoAIF183CocfqPaYlotKCeNovnPXeSCmAX1dOGhCHKBIQmkmL7YU 
TZI1DxiWLlQJBAPY2CWyA26GKGulWzURJa7guizaqGJpghF30U5VdvdKmetYU2gXA 
rhHQ9LxdjGO9L9BWSxg5Y1Z102b8f2Qf78ECQOCNr3VBpBCBhXWAmCSwOCURFUfq 
UWizrJhWPKGvVjuGpHhI/4bm9PXFnS8R7zSNr/XkgDmtjc4YIZ6HAUM-«-6enBAkBi 
yC9jvxdfan9/NdJJUYPMC7AbEIeqeIri/OIBrYiZWX3zIo6OvE2ajFGEuau7sE7Cc 
SaKTZAL5iQUWTrvlufKBAkEAis4KsIA4InxzOlZPRcmPlUVKULvVqyquqsfKP-«NFG 
PTurYiXOC2kXPbBNxyhTDQ6Dw3OBOGhARHSGiuhQQicA2w-- 

一 一 一 一 一 BINIDERSAGPRIVATEOUKBYT————-— Uh 


det main(): 
# 输入 PEM 格式 的 私 钥 
private key = RSA.importKey (PRIVATE KEY PEM) 
# 解密 数据 
decrypt edim eae een DATA 
# 输出 至 屏幕 
print decrypted 


与 加 密 时 一 样 ， 解 密 也 是 通过 RSA.importKey KAn AURAEHAJEAAKBX RSA 对 象 。 接 下 来 我们 
在 decrypt 方法 的 传 值 参 数 中 指定 已 加 密 的 数据 进行 解密 。 上 述 代 码 的 执行 结果 如 LIST 15.36 所 示 。 
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e LIST 15.36 ”执行 结果 


$ python rea cCecryot 9y 
Hello, world! 


NOTE 


为 了 便于 理解 ， 上 述 例子 都 是 直接 在 代码 中 描述 公 钥 和 私 钥 。 实 际 使 用 时 可 以 从 密 钥 文 件 
中 读 取 密 钥 数 据 ， 从 而 提高 效率 。 


15.5 使 用 Twitter 的 API 


随 着 Twitter 在 全 世界 推广 ， 系 统 与 Twitter 联动 的 需求 越 来 越 常 见 。 现 在 有 不 少 封 装 了 
Twitter API 的 Python 模块 ， 这 里 我 们 以 tweepy 为 例 学 习 如 何 使 用 tweepy 模块 。tweepy 几乎 涵 
其 了 所 有 Twitter API， 而 且 能 相对 灵活 地 应 对 Twitter API 目 身 的 规格 变更 。 下 面 我 们 用 Flask 
和 tweepy 来 简单 做 一 个 基于 Web 的 时 间 轴 视图 。 











tweepy 
http://www.tweepy.org/ 











15.5.1 导入 tweepy 
lli LIST 15.37 所 示 ， 通 过 pip 命令 安装 tweepy。 本 书 使 用 了 tweepy 的 3.1.0 版 本 。 


EJ LIST 15.37 用 pip 命令 安装 tweepy 


$ pip install tweepy 


15.5.2 ”添加 应 用 与 获取 用 户 密 钥 


开发 使 用 Tiwtter 的 API 的 应 用 时 ， 需 要 将 应 用 添加 到 Twitter Application Managements F H 
我 们 来 实际 操作 一 下 。 如 图 15.5 所 示 ，Twitter Application Management 可 以 用 Twitter 账户 登录 。 没 有 
账户 时 需要 新 注册 一 个 。 登 录 后 会 进入 Twitter Apps 页 面 ， 该 页 上 显示 了 所 有 已 添加 的 应 用 。 


Twitter Application Management 
http://apps.twitter.com/ 
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wi Twitter Application Man x WC 
€ > Q Qhttps://apps.twitter.com 








W Application Management 


Twitter Apps 


You don't currently have any Twitter Apps. 


Create New App 


Mf Tweet < 3,617 | 


About Terms Privacy Cookies © 2014 Twitter, Inc. 





15.5 已 添加 应 用 的 一 览 页 面 


添加 新 应 用 时 ， 需 要 点 击 Create New App 按钮 进入 添加 页 面 ， 然 后 在 该 页 面 输入 必 填 事项 ， 
如 图 15.6 所 示 。 


wf Create an application | x 


€ > Q d https://apps.twitter.com/app/new 








Wi Application Management 


Create an application 


Application Details 
Name * 


bpbook-example 


Your application name. This is used to attribute the source of a tweet and in user-facing authorization screens. 32 characters max. 


Description * 


bpbook example 


Your application description, which will be shown in user-facing authorization screens. Between 10 and 200 characters max 


Website * 
http-//www.beproud.jp/ 


Your application's publicly accessible home page, where users can go to download, make use of, or find out more information about your application. This fully-qualified URL is used in the 
source attribution for tweets created by your application and will be shown in user-facing authorization screens. 
(If you dont have a URL yet, just put a placeholder here but remember to change it later.) 


Callback URL 


http://127.0.0.1/callback 


Where should we return after successfully authenticating? OAuth 1.0a applications should explicitly specify their oauth callback URL on the request token step, regardless of the value given 
here. To restrict your application from using calibacks, leave this field blank 





15.6 ”用 于 添加 应 用 的 页 面 
本 书 所 用 例子 的 输入 如 下 。 
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Name ( 应 用 名 ) bpbook-example 


Description ( 应 用 的 说 明 ) bpbook example 





WebSite ( 应 用 的 Web 站 点 ) http://www.beproud.jp/ 
Callback URL ( OAuth 认证 后 的 回调 URL ) http://127.0.0.1:5000/callback 
Yes, | agree ( 同意 使 用 条 款 ) A Je [5] se FH ACRI 











系统 上 比较 重要 的 只 有 Callback URL 的 值 。 这 里 指定 的 是 通过 Twitter 站 点 认证 后 重 定 问 访 
问 的 应 用 的 URL。 我 们 需要 在 之 后 开发 的 应 用 中 实现 这 个 URL 的 处 理 。 输 入 所 有 项 目 后 点 击 
Create your Twitter application， 如 有 果 没 有 问题 ， 系 统 会 提示 添加 完成 ， 并 显示 已 水 加 应 用 的 详细 
言 息 ， 如 图 15.7 所 示 。 





wf bpbook-example | Twit x 
€ > Q gg https://apps.twitter.com/app/7323242/show 








W Application Management 


bpbook-example Test oAutn 


Details ^ Settings Keys and Access Tokens Permissions 


dini bpbook example 
i: http-//www.beproud.jp/ 


— 
Organization 
Information about the organization or company associated with your a, cation YS information 1S optional 


Organization 


Organization website 


PEP Sn 


Your application's Consumer Key and Secret are used to authenticate r ests to the Twitter PI 


Access level Read-only (modify app permissions) 
Consumer Key (API Key) bEwP2WOBTHZzSOfWTA4LhEZz6sP (manage keys and access tokens) 


Callback URL http://127.0.0.1/callback 





Sign in with Twitter No 


15.7 已 添加 应 用 的 详细 信息 ( 添加 完成 时 ) 


详细 信息 页 面 的 Keys and Access Tokens 标签 页 的 Application Settings 部 分 显示 了 Consumer 
Key (用户 密 钥 ) 和 Consumer Secret ( 用 户 机 密 ) 字符 串 。 使 用 Twitter 的 API 时 需要 用 到 这 
字符 串 以 及 下 面 即将 学 习 的 访问 令 牌 和 访问 令 牌 机 密 。 

Access Level 表示 应 用 可 以 对 用 户 数据 做 哪些 操作 ， 有 Read-only ( HE )、Read and Write 
( 可 读 写 )、Read,Write and Access direct messages ( 可 读 写 及 访问 私信 ) 3 种 操作 可 供 选 择 。 我 们 
这 里 开发 的 时 间 轴 视图 只 有 读 取 操作 ， 因 此 用 Read-only 就 足够 了 。 











第 15 章 方便 好 用 的 Python 模块 | 385 


15.5.3 获取 访问 令 牌 
OAuth 的 访问 令 牌 是 为 每 一 个 使 用 应 用 的 用 户 分 别 配 发 的 仁 。 可 以 通过 已 添加 应 用 的 详细 
言 息 页 面 为 已 添加 应 用 的 用 户 手动 配 发 访问 令 牌 。 点 击 Keys and Access Tokens 标签 页 下 部 的 
Create my Access token 即 可 完成 访问 令 牌 的 配 发。 点 击 Regenerate My Access Token and Token 
Secret 可 以 作废 已 有 令 牌 并 重新 配 发 新 的 。 访 问 令 牌 以 图 15.8 所 示 的 字符 串 形 式 给 出 。 我 们 将 
在 应 用 中 用 到 Access Token ( 访问 令 牌 ) 和 Access Token Secret ( 访问 令 牌 机 密 )。 














wi bpbook-example | Twit x 





€ > Q Gghttps://apps.twitter.com/app/7323242/keys 





Your Access Token 
This access token can Bj 


| 1 be used to make API requests on your own account's behalf. Do not share your access token secret with anyone 
Access Token 460466270-ZHdLp7 QOYOoKTX7s2CQS8Ac9xBFjw1S1pap392cVh 
Access Token Secret qzgD6fMPu7PMacoMFb6yOnHkYxXzmTtO2XBAzfhE2DZyD 
Access Level Read-only 
Owner bpbook 


Owner ID 460466270 


Token Actions 


Regenerate My Access Token and Token Secret Revoke Token Access 


2014 Twitter, Inc. 








15.8 获取 自己 的 访问 令 牌 


如 果 应 用 只 使 用 目 己 的 Twitter 账户， 那么 我 们 开发 应 用 时 只 考虑 上 面 获取 的 访问 令 牌 即 
可 。 如 果 应 用 需要 任意 多 个 用 户 使 用 不 同 的 Twitter 账户 ， 则 需要 使 用 基于 Web 的 Authorize 
URL 方式 认证 ， 从 应 用 端 获 取 访 问 令 牌 。 我 们 即将 开发 的 时 间 轴 视图 属于 后 者 。 











15.5.4 调用 Twitter API 


用 tweepy 调用 Twitter API 时 ， 需 要 用 到 OAuthHandler 类 和 API 类。 下面， 我 们 使 用 前 面 
获取 的 用 户 密 钥 和 访问 令 牌 ， 获 取 Twitter 主页 上 显示 的 时 间 轴 ， 代 码 如 LIST 15.38 所 示 。 





© LIST 15.38 tweepy hello.py 


u Coding: ee 
from tweepy import OAuthHandler, API 
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# 用 户 密 钥 ( 本 应 用 的 ) 

CONSUMER KEY - 'Consumer key! 

CONSUMER SECRET - 'Consumer secret' 

# 访问 令 牌 (bpbook 用 户 的 ) 

ACCESS TOKEN - 'Access token' 
ACORSSOTONENOCSEOCREBT — "Access token secret! 


der maim () s 
# 生成 OAuth fJ handler 
handler = OAuthHandler(CONSUMER KEY, CONSUMER SECRET) 
# 25 handler 设置 访问 令 牌 
handler.set access token(ACCESS TOKEN, ACCESS TOKEN SECRET) 
# CER API 实例 
api = API (handler) 
# 用 API 获取 时 间 轴 
statuses = apil. nome timeline () 


EOR gtrarcues imn grTacusesg: 


# 将 获取 的 状态 的 前 15 个 字符 输出 到 页 面 上 


printe os RE 3 (status User sereen name, STATUS TEE I:15]) 


it o name _ --c maim ': 


请 各 位 自行 将 上 述 代码 中 的 CONSUMER KEY, CONSUMER SECRET, ACCESS TOKEN, 
ACCESS TOKEN SECRET 部 分 替换 为 前 面 获 取 的 值 。 先 在 OAuthHandler 类 的 构造 函数 中 指定 
用 户 窗 铀 和 用 户 机 蜜 ， 然 后 用 OAuthHandler 的 set access token 方法 给 handler 设置 对 应 的 访问 
Shio E API 类 的 构造 函数 中 指定 handler 对 象 ， 让 我 们 能 够 使 用 API 调用。 没有 设置 访问 令 
牌 的 handler 无 法 使 用 绝 大 多 数 的 API 调用 。home timeline 方法 最 多 可 以 返回 20 条 首页 的 时 间 





轴 信 息 。 
上 述 代 码 的 执行 结果 如 LIST 15.39 所 示 。 


© LIST 15.39 执行 结果 


$ python ve Ne 

bpbook: 测试 

liblar jp:【 有 关 添 加 功能 的 通知 】 书籍 相关 
connpass_jp:【 有关 功能 修改 的 通知 】 多 天 以 来 
liblar jp: 【有 关 维 护 王 作 已 全 面 结 来 的 通知 】 
beproud jp: BePROUD 公司 现在 就 Web 

( 以 下 省 略 ) 





发 生 TweepError: HTTP Error 401: Unauthorized 错误 时 ， 需 要 查看 用 户 密 钥 和 访问 令 牌 是 否 
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有 误 。 另 外 ， 执 行 环境 的 系统 时 间 与 实际 时 间 不 一 致 也 会 导致 这 个 错误 。 
K home timeline 之 外 ， 还 有 许多 方法 封装 了 API。 详 细 内 容 可 以 查看 tweepy 文档 的 API 
Reference 来 了 解 。 





tweepy API Reference 








http://tweepy.readthedocs.org/en/v3.0.0/api.html 





在 这 个 例子 中 ,我 们 是 下 接 在 代码 中 描述 访问 令 牌 (ACCESS_TOKEN、ACCESS_TOKEN_ 
SECRET ) 的 。 对 于 只 通过 单一 用 户 获 取 时 间 轴 信息 或 进行 发 言 的 应 用 C 比如 TwitterBot 等 ) 而 
言 ， 由 于 不 需要 用 于 认证 的 UI， 所 以 使 用 这 种 方法 不 会 有 问题 。 








15.5.5 ”编写 用 Twitter 认证 的 系统 
下 面 我 们 编写 一 个 用 Twitter 账户 登录 (认证 ) 并 根据 各 Twitter 账户 的 权限 使 用 API 的 系 
统 。 编 写 这 个 系统 中 需要 用 到 Twitter 的 认证 页 面 ， 还 要 获取 各 个 账户 的 访问 令 牌 。 从 登录 的 起 
始 处 理 到 使 用 API 的 处 理 流 程 如 下 所 示 。 





(D 用户 通过 Web 浏览 需 访 问 应 用 的 登录 URL 

D 应 用 从 Twitter 获取 请 求 令 牌 

(3) 应 用 将 获取 到 的 请 求 令 牌 保存 在 会 话 中 

(9 MHIE Twitter 的 认证 URL 3& Ilt 4 4 hg TE FIAT E E Fe] Ue 

(5) 用 户 通 过 Web 浏览 需 在 Twitter 的 认证 页 面 对 应 用 授权 

(6) 用 户 根 据 Twitter 端的 重 定 问 啊 应 ， 通 过 Web 浏览 需 访 问 应 用 的 回调 URL Ci 4 88 
属性 ) 

CO 应 用 从 会 话 中 还 原 请 求 令 牌 

应 用 从 Twitter 获取 用 户 的 访问 令 牌 

9) 应 用 依据 访问 令 牌 使 用 Twitter 的 API 




















使 用 tweepy 可 以 轻松 完成 的 生成 带 属性 的 URL 、@) 的 获取 令 牌 、@) 的 依据 访问 令 牌 使 用 
Twitter API。 下 面 我 们 看 一 下 web 应 用 ， 它 使 用 Flask 和 tweepy 对 Twitter 账户 进行 认证 ， 然 后 
获取 时 间 轴 信息 并 使 之 显示 在 页 面 上 ， 代 码 如 LIST 15.40 所 示 。 





© LIST 15.40 tweepy auth.py 
= codings uti-8 


crom lask import Flask, render template, cule cues EEECc ee 
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from tweepy import OAuthHandler, API 


application = Flask( name ) 
A e e 


application. secret key = "my secret key! 


# 用 户 密 钥 
CONSUMER KEY = 'Consumer key! 
CONSUMER SECRET = Consumer secret ' 


SepgcuM CCCII 


"nn 从 会 话 获 取 访 [5] Sm 的 ER 


recura sesgo, Get l accese Cokan! ) 


def set access _ token (access token): 


"n" 在 会 话 中 保存 访问 令 牌 的 函数 


session | "access _ token'] = access token 


det get _regquest token (key) : 
""" 从 会 话 获取 请 求 令 牌 的 函数 


return session.get (key) 


ciem, Exe coepere deeem ee ehem) s 
'"" 在 会 话 中 保存 请 求 令 牌 的 函数 


session[key] = token 


def get oauth handler(): 
""" 返回 Tweepy 的 OAuth handler 的 函数 


return OAuthHandler (CONSUMER KEY, CONSUMER SECRET) 


derneucrEApu ucc em) 
""" 指定 访问 令 牌 返回 API 实例 的 函数 
handler = get Oaucha nanciler () 
handler.set_access token (access token[0], access token [1] ) 
api = API (handler) 


return api 


def 


def 


def 


def 
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set user (user): 


"wn 会 话 中 保存 用 户 信 息 的 EE 


# 以 可 JSON 序列 化 的 字典 对 象 格式 保存 在 会 话 中 


session['user'] = {'screen name': user.screen name] 


get user t) s 


"nnn 从 会 话 获 取 用 户 信 息 的 EK 


return session.getí('user') 


is login) s 
""" 返回 是 否 为 登录 ) 





大 态 
MSN: 


retum nort not get access mek en 


clear cuc 


"nnn 删 IE 的 值 


session.clear() 


Gapplication-route(!/") 


def 


index(): 
"nnn An 
使 用 模板 显示 页 面 


# 根据 模板 显示 页 面 


return render templete (' index- bb caeca uM eere Sn eu 


Gapplication.route('/login') 


def 


login () s 
nme S RK URD 
开始 Twitter 认证 
handler = get oauth handler () 
# 获取 认证 URL 
auta url = handler. cre ci pordgez crore maed 
# 请 求 令 牌 保存 在 会 话 中 
Set request _ token ( 
handler. request token E) aera 
handler, request Eoken [ "oaut tokem secret" |) 
# 重 定 向 到 认证 URL 


return redirect (auth url) 


389 
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Gapplication.route('/callback') 
det calliecik() e 

""" 回调 URL 

Twitter 认证 后 的 回调 URL 

# 用 GET 方法 获取 OAuth 的 回调 属性 

ceuta Token ees args. get oa en 

ceuta veritier = request args. get oaut veritier!" ) 

# 取消 时 重 定 向 到 首页 

dL nOr Cauta token and not cautn veritier: 
return redirect('/') 

# RX OAuth fj handler 

handler = get oauth handler () 

# 从 会 话 获取 请 求 令 牌 并 设置 给 handlet 

Dogs ocn Mecca oem ocu em 

handler.request token = { 
Loaveseelen: eeeol en 
"auttm tOkem Secret! ee 

j 

# 获取 访问 令 牌 

Hoeccosmocene-anuucdescceuMudcccscubOlen esu EH Ie) 

# 将 访问 令 牌 保存 在 会 话 中 

set access token (access _ token) 

# 获取 API 实例 

apl = get api lacecess token) 

# 获取 登录 用 户 的 信息 并 保存 至 会 话 

set user (api.me ()) 

# 重 定向 到 首页 


rebum 二 EC) 


Gapplication.route('/logout') 
def logout(): 
"un ZEB URL 
从 会 话 中 删除 登录 ) 
# 删除 会 话 中 的 登录 信息 
clear session () 
# 重 定向 到 首页 


return redireer(!/') 


大 态 的 信息 





Gapplication.route('/timeline') 


def timeline(): 
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""" 显示 时 间 轴 信息 的 页 面 
需要 认证 
# 获取 登录 状态 
it not is diee proie Cs 
# 没有 登录 则 重 定向 到 首页 
return redirect('/') 
# 从 会 话 获取 访问 令 牌 
access token = get access eH 
it mor access tokens 
# 无 法 获取 访问 令 牌 时 
# 清除 会 话 并 重新 开始 
clear session () 
return redirect('/') 
# 获取 API 实例 
api = get api(access token,) 


# 调用 Twitter API 获取 时 间 轴 信息 


statuses = api.home timeline () 

# 通过 模板 显示 页 面 

recurn rencer cemplate ("timeline ntm", Estates isses 
it name == ' main  ': 


# mo IPIBHE127.0.0.1 89 5000 3 OMITA RH 
application atmi anO rc 0m estu ee 
HP, CONSUMER KEY, CONSUMER SECRET 的 值 需要 替换 成 之 前 为 应 用 获取 的 值 。 在 上 
面 的 例子 中 ， 我 们 用 Flask 的 会 话 保 存 了 请 求 令 牌 。 该 段 代 码 使 用 了 index.html 和 timeline.html 
两 个 模板 文件 ， 这 两 个 文件 保存 在 templates 目录 下 ， 其 内 容 如 LIST 15.41 所 示 。 





© LIST 15.41 templates/index.html 


<html> 
<head> 
<meta http-equiv="Content-type" content="text/html; charset=utf-8" /> 
<title>Twitter 认证 </title> 
</head> 
<body> 
人 
«p» 登录 名 : {{ user.screen name }}</p> 
guls 
<li><a href="/timeline"> 获取 时 间 轴 信息 </a></1i> 
下 下 本 


</ul> 
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«ul» 


«li»«a href-"/login"» &€* «/a»«/li» 


</ul> 
(* endif %} 
</body> 
</html> 





index.html 在 未 认证 状态 下 显示 开始 认证 处 理 的 URL 链接 ， 在 已 认证 状态 下 则 显示 Twitter 
的 昵称 (登录 名 )、 获 取 时 间 轴 信息 的 处 理 以 及 登 出 处 理 的 链接 ( LIST 15.42 )。 


© LIST 15.42  templates/timeline.html 


«html» 
<head> 
<meta http-equiv="Content-type" content="text/html; charset=utf-8" /> 
<title> 时 间 轴 信息 的 显示 </title> 
</head> 
539189 S25 
gels 
l> for status in statuses $) 
<dt>{{ status.user.screen name }}</dt> 
<dd>- { status text s 
(2 endfor $] 
F 
</body> 
</html> 


timeline.html 用 来 显示 获取 到 的 时 间 轴 信息 ( 状态 )。 准备 好 源码 及 模板 后 ， 用 python 命令 
执行 tweepy_auth.py MJA Ak, ARIBUN LIST 15.43 所 示 。 


© LIST 15.43 用 python 命令 执行 tweepy_auth.py 


$ python tweepy_auth.py 
> Rumaing on htta: 212: 901 5/0/09 


* Restarting with reloader 


NOTE 


本 例 是 用 5000 端口 启动 开发 服务 器 的 ， 因 此 请 保证 SSH 隧道 的 主 OS sz OS 的 5000 s 
口 相 连 Un 


启动 服务 器 后 ， 打 开 Web 浏览 器 试 着 访问 http://127.0.0.1:5000/。 刚 开始 时 我 们 
处 于 未 登录 状态 ， 所 以 会 显示 有 登录 链接 的 页 面 。 点 击 登 录 连 接 ， 随 后 将 跳 转 至 Twitter 的 认证 
页 面 ， 我 们 会 看 到 如 图 15.9 所 示 的 应 用 授权 请 求 信息 以 及 按钮 。 








第 15 章 方便 好 用 的 Python 模块 | 393 


W Twitter / Authorize ar 





€ c | & Twitter, Inc. [US] | https;//twitter.com/oauth/authorize?oauth consumer key-FQXaXk4wWXxEQEgOx5pcw&oauth nonce-497ad2f1b7fedad1f380cf108e64876 *r | : 


v o 





Authorize bpbook-example to use 
your account? 


à bpbook-example 
Authorize app Cancel 
www.beprouc j 
opbook example 


This application will be able to: 
* Read Tweets from your timeline. 
» See who you follow. 


Will not be able to: 

。 Follow new people 

* Update your profile 

* Post Tweets for you. 

* Access your direct messages. 
+ See your Twitter password 


can revoke access to any application at any time from the Applications tab of your Settings page 


jn you continue to operate under Twitter's Terms of Service. In particular, some usage information will be shared back with 





15.9 Twitter 的 应 用 授权 页 面 


点 击 页 面 中 的 授权 按钮 之 后 ， 页 面 将 重 定 癌 到 我 们 添加 应 用 时 填写 的 Callback URL， 处 理 
也 将 返回 到 应 用 闪 。 获 取 访 问 令 牌 和 个 人 信息 后 ， 应 用 显示 市 有 用 户 名 、 获 取 时 间 轴 信息 链接 
以 及 登 出 链接 的 登录 状态 界面 。 我 们 点 击 获 取 时 间 轴 信息 的 链接 之 后 ， 应 用 会 使 用 用 户 的 访问 
令 有 牌 获取 时 间 轴 信息 并 显示 在 页 面 上 。 至 此 ， 时 间 轴 视图 的 应 用 开发 完毕 。 














NOTE 
介绍 的 时 间 轴 视图 是 将 访问 令 牌 保存 了 在 会 话 中 ， 会 话 一 旦 过 期 就 需要 重新 获取 令 牌 。 
我 们 可 以 通过 将 访问 令 牌 存放 在 数据 库 中 来 避免 这 一 问题 。 


15.6 使 用 REST API | 





系统 间 协 作 及 使 用 外 部 服务 时 ， 经 常会 用 REST API 作 接 口 。REST API 可 以 用 Python 标准 
模块 urllib 和 json 来 控制 ， 不 过 本 书 要 讲 的 是 Requests 的 使 用 方法 。 





Requests: HTTP for Humans 
http://docs.python-requests.org/en/latest/ 
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15.6.1 REST 简介 


REST ( Representational state transfer， 具 象 状态 传输 ” ) 是 一 种 软件 架构 。 它 于 2000 年 由 
Roy Fielding 提出 ， 是 几 种 软件 设计 原则 的 集合 。 

不 过 ， 现 在 人 们 广泛 使 用 的 REST 和 REST API 通 常 指 “ 在 HTTP. 上 运行 的 非 SOAP JF 
RPC 的 API 。 

REST API 的 特征 如 下 。 


e Tr HTTP 上 运行 

e 数据 被 称 为 “资源 ” 

e REST API 可 使 用 的 资源 具有 唯一 的 URL 

e GET/POST/PUT/DELETE 等 HTTP 方法 分 别 对 应 资源 的 获取 /保存 /和 窗 盖 /删除 等 操作 
。 通 过 JSON、XML 等 格式 收发 数据 

请 求 成 功 、 请 求 失败 等 处 理 结果 体现 在 状态 代码 中 

















如 果 要 使 用 REST API， 则 需要 用 到 HTTP 客户 端 。 在 shell 命令 或 shell 脚本 中 使 用 时 要 用 
curl， 在 程序 中 使 用 时 则 要 用 HTTP 26 Py tEF EE o 

















REST - Wikipedia 
http://zh.wikipedia.org/wiki/REST 

Fielding Dissertation CHAPTER 5 Representational State Transfer (REST) 
http://www.ics.uci.edu/-fielding/pubs/dissertation/rest arch style.htm 











15.6.2 导入 Requests 
如 LIST 15.44 所 示 ， 用 pip 命令 安装 Requests。 本 书 使 用 的 是 Requests 的 2.5.0 版 本 。 


加 LIST 15.44. 用 pip 命令 安装 Requests 


$ pip install requests 


15.6.3 ”导入 测试 服务 器 


要 检查 Requests 模块 的 运行 状况 束 必 须 使 用 Web 服务 各。httpbin 模块 是 基于 Python 开发 
的 HTTP 测试 服务 右 。 本 书 将 用 httpbin 模块 作为 测试 服务 右 来 讲解 Requests 的 使 用 方法 。 





有 时 也 被 译 为 表述 性 状态 转移 或 表述 性 状态 传输 等 。 译 者 注 
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dll LIST 15.45 所 示 ， 用 pip 命令 安装 httpbin。 本 书 使 用 的 是 httpbin 的 0.2.0 版 本 。 


© LIST 15.45 用 pip 命令 安装 httpbin 


$ pio nnercall netadLn 


httpbin 的 测试 服务 器 用 LIST 15.46 中 的 命令 启动 。 


Ej LIST 15.46 JAZ) httpbin 的 测试 服务 器 
$ python =m Mecon, Core 
» Running on hnttp://127:.0.0.1:5000/ 


在 导入 Requests 模块 之 前 ， 先 用 curl 命令 检查 测试 服务 器 的 运行 状况 。 
在 测试 服务 器 已 启动 的 状态 下 运行 LIST 15.47。 如 果 运 行 正常 ， 屏 幕 上 将 显示 如 下 所 示 的 
JSON 格式 报告 。 





© LIST 15.47 用 cur| 命令 检查 测试 服务 器 的 运行 状况 


$ curl "http://127.0.0.1:5000/get?foo-bar" # 向 测试 服务 器 发 送 GET 请 求 


{ 
"args": ( # args 为 GET 参数 
ood EU DS 
jc 
"headers": { 
accept" g M /Ww 
!Contemsrt-isength': uu 
ioc nec misc "m, 
UTOS EAN: UE OO cESq OMM 
User-Agent; Mourl 9 3599" 
E 
cp reputo de? yog dune 
marl", “heto //127.:0.0.1:5000/get? oe en 
j 
$ curl -X post -d foo-bar http://127.0.0.1:5000/post # 向 测试 服务 器 发 送 POST AK d 
{ 
target ni 
"data": "", # data 为 发 送 数 据 的 正文 (未 经 过 编码 的 表单 数据 除外 ) 


"files": (), # files 为 被 上 传 的 文件 
"form": { # form 为 经 过 编码 的 表单 数据 


"foo": "bar" 

ls 

"headers": { 
"Accept": WI eM 


Lo onienmcchenmct c. 
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"Content-Type": "application/x-www-form-urlencoded", 
JHOSS M NET COE qe 
"Uuseremgent'- curl 359" 


t 

Iason: mme 

Mo6ggumbéj129- 905€ T0 

nmelne heto: //127.0.0.1:5000/p08t" 





可 以 看 出 ， 测 试 服务 大 具有 将 请 求 的 内 容 以 JSON 格式 返回 的 功能 。 


NOTE 


在 Windows 上 使 用 curl 命令 时 需要 安装 命令 工具 。 


cURL - Download 
http://curl.haxx.se/download.html 


15.6.4 ”发 寺 GET 请 求 


用 Requests 发 送 GET 请 求 ， 具 体 代 码 如 LIST 15.48 所 示 。 





© LIST 15.48 requests get.py 
u coding: VEE=8 
qmporbt pprint 


import requests 


def main(): 


# GET 参数 以 字典 形式 通过 params 传 值 参数 指定 


response = requests.get( 
"netos //127-0:0.1:5000/096t", 
parame- fool: oa 


4 使 用 响应 对 象 的 json 方法 可 以 获取 转换 为 Python 字典 对 象 的 JSON 数据 


pprint -oprint (response. Jeon) ) 


在 requests.get KAUPE EX Z URL, H params 关键 字 传 值 参数 指定 GET 2x. IREA 


回 的 啊 应 为 JSON 格式 ， 因 此 要 用 json 方法 将 其 转换 为 字典 形式 再 显示 到 页 面 上 。 上 述 代码 的 
执行 结果 如 LIST 15.49 所 示 。 
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E LIST 15.49 ”执行 结果 


$ python recguests eer 

(un Ue el ac og foo a 

u'headers': (u'Accept': u'*/*', 
u'Accept-Encoding': u'gzip, deflate', 
u'Connection!': u'keep-alive', 
u'content-hengti': utt 
uConcenmc= Ios d s w”, 
woese a usse 
u'User-Agent': u'python-requests/2.5.0 CPython/2.7.8 Linux/3.13. 

0-35-generic'}, 

u'origin': W127.0.0,.1!, 


Uuri u hep t doo m ere reb 5000/ get toc bar!) 


15.6.5 发达 POST 请 求 


用 Requests 发 送 POST 请 求 ， 具 体 代 人 码 如 LIST 15.50 所 示 。 





© LIST 15.50 requests post.py 


# coding: utf-8 
amport o ppzcut 


import requests 


def main(): 
# POST 参数 以 字典 形式 通过 第 二 个 传 值 参数 指定 
response = requests.post( 
heto: LE The 1e (OE IB SS (000.9) T9 YS SES 1 ， 
foot ipart) 
# 使 用 啊 应 对 象 的 json 方法 可 以 获取 转换 为 Python 字典 对 象 的 JSON 数据 


porrat. porine (responge,. een 


1 
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request.post KA P F5 T X URL 和 了 POST 824, 25 POST 参数 指定 的 字典 会 被 编码 为 


URL 发 送出 去 。 这 段 代 码 的 执行 结果 如 LIST 15.51 所 示 。 


E LIST 15.51 执行 结果 


$ python e exem eee Post .oy 
mes a N, 


u'data'' wu 
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uS 
Tue esame UR o u Bar e 
u'headers': ([u'Accept': u'*/*', 
u'Accept-Encoding': u'gzip, deflate', 
u'Connection'!': u'keep-alive', 
u'Content-Lengtn': u'7'» 
u'Content-Type': u'application/x-www-form-urlencoded', 
uses mu lcqsquss te 
u'User-Agent': u'python-requests/2.5.0 CPython/2.7.8 Linux/3.13. 
0-35-generic'j], J 
u'gson': None; 
ulorigin' s M127.0.0,17'. 


uturi ea bete aa o Ora dE 8 5000 /oe 


15.6.6 发送 JSON 格式 的 POST 请 求 


有 些 API 接口 要 求 直 接 发 送 JSON 格式 的 字符 串 ， 不 能 将 数据 编码 为 URL。 用 Requests 以 
JSON 格式 字符 串 的 形式 发 送 POST 请 求 ， 具 体 代码 如 LIST 15.52 所 示 。 





© LIST 15.52 requests post json.py 
u Coding: ere 
impon EE a 
import json 


import requests 


def main (): 
# 指定 json.dumps 生成 的 字符 串 之 后 ， 可 以 直接 发 送 数据 而 不 进行 URL 编码 
# 需要 明确 指定 Content-Tpye 
response = requests.post( 
RETO: /27.0.0.125000/75o5SE 1， ， 
son dumps rool mbar n), 
headers-['Content-Type': 'application/json'}) 


pprint .pprint (response.json()) 


it mam =a | marin ': 


main() 





post PAZ BS FEES AU REPAS AUS ENYS.T THBESUBIERSX TN BIZ EB, 
不 进行 URL 编码 。 这 上 段 代 码 的 执行 结果 如 LIST 15.53 所 示 。 


第 15 章 


© LIST 15.53 ”执行 结果 


$ python requests post json.py 

are 

aa 

Ue s 

utform: IT, 

u'headers'!: (u'Accept': x 
u'Accept-Encoding': u'gzip, deflate', 
u'Connection!': u'keep-alive', 
u'Content-Lhength': u'14'; 
u'Content-Type': u'application/json', 


uos cu oy ug 9D. 


方便 好 用 的 Python 模块 


u'User-Agent': u'python-requests/2.5.0 CPython/2.7.8 Linux/3.13. 


0-35-generic'], 
ie 
u'origrma’ s Mili27.0.0.17., 


/L227 00 :S000 Sst 


15.6.7 使 用 GET/POST 之 外 的 HTTP 方法 
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HE API 还 会 用 到 GET, POST 之 外 的 HTTP 方法 (PUT、DELETE、HEAD、OPTIONS )。 
Requests 同样 为 这 些 方法 准备 了 对 应 的 图 数 ， 人 代码 如 LIST 15.54 所 示 。 


© LIST 15.54 requests other methods.py 
u Coding, ubt-8 


import requests 


def main(): 


requests put aereo dA / 162 7 (095 016 156 S000 put rool bar y) Es DUT 
requests.delete('http://127.0.0.1:5000/delete') # DELETE 
requests.head('http://127.0.0.1:5000/get') d HEAD 
noeguesbcvoptdonsdohttpo2y Qui ogoAopb ons E T OPNS 

itf name  -- ' main  ': 
main() 


执行 了 这 段 代 码 之 后 ， 程 序 会 向 服务 器 发 送 HTTP Hj PUT, DELETE, HEAD, OPTIONS 





方法 的 请 求 ， 获 取 啊 应 后 执行 结 
H[ UL, H Requests 可 以 轻松 使 用 以 HTTP 为 接口 的 REST API, 
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15.7 Zi 














在 开发 应 用 的 过 程 中 ， 我 们 多 少 都 会 遇 到 些 难 题 ， 而 方便 好 用 的 模块 往往 是 解决 难题 的 方 
法 之 一 。 本 章 介 绍 了 几 个 开发 中 的 难题 以 及 解决 相应 难题 的 Python 模块 。 希望 各 位 多 多 利用 本 
书 以 及 其 他 各 种 信息 来 源 ， 收 集 难 题 的 解决 方案 以 及 好 用 模块 的 信息 。 多 了 解 一 些 可 以 拿 来 就 
用 的 模块 是 大 幅 缩短 开发 时 间 的 有 效 途 径 。 














附录 A VirtualBox 的 设置 


附录 B OS (Ubuntu ) 的 设置 





附录 A VirtualBox 的 设置 


近年 来 ，PC 的 虚拟 化 技术 不 断 发 展 ， 个 人 已 经 能 够 轻松 地 搭建 并 使 用 虚拟 机 了 。 随 着 虚拟 
机 个 人 使 用 的 简化 ， 越 来 越 多 的 开发 者 也 开始 利用 虚拟 化 软件 搭建 本 地 开发 环境 。 这 里 我 们 学 
习 一 下 将 Oracle 的 VirtualBox 设置 为 虚拟 机 的 流程 。VirtualBox &— 3X x4 Windows, OS X, 
Linux 的 免费 虚拟 化 软件 。 

这 里 我 们 将 本 地 计算 机 称 为 主 OS， 虚 拟 机 称 为 客 OS. E OS "my A SELA OS X 为 例 进行 
说 明 。 


A.1 安装 VirtualBox j 





首先 从 VirtualBox 的 下 载 页 面 了 下 载 适 合 主 OS 的 VirtualBox。 本 书 使 用 了 编写 时 (2014 年 
11 月 ) 的 最 新 版 本 VirtualBox 4.3.18 (图 A.1 )。 





Here, you will find links to VirtualBox binaries and its source code. 


About | 
Screenshots . VirtualBox binaries 
Downloads By downloading, you agree to the terms and conditions of the respective license. 
Documentation * VirtualBox platform packages. The binaries are released under the terms of the GPL version 2. 
End-user docs i o VirtualBox 4.3.18 for Windows hosts -:x86/amd64 
. : o VirtualBox 4.3.18 for OS X hosts =>x86/amd64 
Technical docs — - o VirtualBox 4.3.18 for Linux hosts 
Contribute ; o VirtualBox 4.3.18 for Solaris hosts G>amd64 
Community * VirtualBox 4.3.18 Oracle VM VirtualBox Extension Pack SAll supported platforms 


Support for USB 2.0 devices, VirtualBox RDP and PXE boot for Intel cards. See this chapter from th 
Pack. The Extension Pack binaries are released under the VirtualBox Personal Use and Evaluation L 
Please install the extension pack with the same version as your installed version of VirtualBox! 

If you are using VirtualBox 4.2.26, please download the extension pack œ here. 

If you are using VirtualBox 4.1.34, please download the extension pack =œ here. 

If you are using VirtualBox 4.0.26, please download the extension pack œ here. 


A.1 "FE VirtualBox 


下 载 完成 之 后 按照 各 OS MB SEXETIOE. DRE A.2 所 示 的 局 动 界 面 时 ， 表 示 


VirtualBox 安装 完毕 。 


(D https://www.virtualbox.org/wiki/Downloads 
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eoe Oracle VM VirtualBox 管理 器 
4 X wv a 
新 建 (N) 设置 (S) 清除 启动 (Tv 
欢迎 使 用 虚拟 电脑 控制 台 ! 
窗口 的 左边 用 来 显示 已 生成 的 虚拟 电脑 . 现在 是 空 的 ， 因 为 你 还 没有 新 建 任何 虚拟 电脑 
sea Y 


A \ 
- 


你 可 以 按 36? 键 来 查看 帮助 ， 或 访问 www.virtualbox.org 
查看 最 新 信息 和 新 闻 . 











A.2 VirtualBox 的 启动 界面 


A.2 新 建 虚拟 机 | 


接 下 来 在 VirtualBox. 上 新 建 虚 拟 机 。 点 击 VirtualBox 的 “新 建 ”按钮 (图 A.3 )。 





虚拟 电脑 名 称 和 系统 类 型 
请 选择 新 虚拟 电脑 的 描述 名 称 及 要 安装 的 操作 系统 类 型 。 
此 名 称 将 用 于 标识 此 虚拟 电脑 。 
: 名 称 : [my ubuntu ny 
N 类 型 : — Linux ^ — hd 
z 
版 本 : | Ubuntu (64-bit) 
`~ 
J 








专家 模式 返回 取消 
A.3 创建 虚拟 机 
本 例 中 的 OS 类 型 的 配置 如 下 。 


e 操作 系统 : Linux 
e 版 本 : Ubuntu ( 64 bit) 
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图 A.3 中 设置 了 64 bit 版 的 Ubuntu， 各 位 可 按照 目 己 的 客 OS 进行 更 改 。VirtualBox 的 版 本 
有 Ubuntu 和 Ubuntu ( 64 bit) 可 选 。 点 击 下 一 步 之 后 系统 会 询问 下 述 内 容 ， 各 位 请 按照 自己 的 环 
境 进行 设置 。 


。 内 存 

。 虚 拟 硬盘 

。 虚 拟 盘 的 文件 类 型 
。 虚 拟 盘 的 容量 


设置 完成 后 ,一 个 空 的 虚拟 机 镜像 就 创建 好 了 ( 图 A.4 )。 








® ® Oracle VM VirtualBox 管理 器 
m 1 ^X 一 ^ 
JW m T s 
新 建 (N) 设置 (S) 清除 启动 (T) 
[92 my ubuntu | i 常规 
| H| O EXA |a 
my ubuntu 
MUR Ubuntu (64-bit) 


LE 


| 内 存 大 小 : 512 MB 
| 启动 顺序 : 软驱 , 光驱, 硬盘 
| 硬件 加 速 : VT-x/AMD-V, ECÉZ) 71 








— 


大 小 : 
TEANS: ER 
| 录像 : 禁用 





G 存储 
| 控制 器 :IDE 
第 二 IDE 控 制 器 主 通道 : [光驱 ] 没有 盘 片 
控制 器 : SATA 
| SATA 端口 0: my. ubuntu.vdi (普通 , 8.00 GB) 


> 声音 


| 主机 音频 驱动 CoreAudio 
控制 芯片 : ICH AC97 


m) 网 络 

网 卡 1: Intel PRO/1000 MT 桌面 (网 络 地 址 转换 (NAT)) 

(y USB 设 备 

USB 控制 器 : OHCI, EHCI 

| 设备 筛选 : ”0 (0 活动 ) | 
图 A.4 虚拟 机 新 建 完 毕 




















A.3 备份 虚拟 机 








在 阅读 本 书 的 过 程 中 ， 各 位 会 过 到 许多 服务 右 设 置 的 变更 。 在 修改 设置 时 ， 难 人 免 出 现 设置 
错误 甚至 设置 损坏 ， 导 致 虚拟 机 无 法 使 用 。 为 防备 这 种 情况 发 生 ， 我 们 要 为 当前 已 设置 完毕 的 
虚拟 机 做 好 备份 ， 以 便 出 了 问题 能 从 头 再 来 。 

接 下 来 学 习 一 下 如 何 备 份 虚拟 机 以 及 如 何 从 备份 还 原 。 使 用 VirtualBox 备份 虚拟 机 的 方法 
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有 许多 ， 这 里 我 们 选 其 中 比较 简单 的 “虚拟 电脑 的 导出 与 导 人 ”进行 学 习 。 

这 里 提 到 的 虚拟 电脑 是 对 包含 设置 在 内 的 所 有 文件 进行 备份 的 机 制 。 该 机 制 将 备份 数据 以 
OVA ( Open Virtualization Format Archive ) 文件 的 形式 保存 ， 当 我 们 的 虚拟 机 出 现 问 题 时 ， 只 要 
有 这 个 文件 ， 就 可 以 在 VirtualBox 上 将 虚拟 机 恢复 到 导出 时 的 状态 。 如 有 末 只 是 想 临 时 保存 虚拟 
机 的 状态 ， 还 可 以 使 用 VirtualBox 的 “快照 ”功能 。 

备份 前 先 关 闭 客 OS。 关 闭 后 依次 选择 “VirtualBox > 管理 > 导出 虚拟 电脑 ”。 点 击 导 出 虚拟 
电脑 后 会 出 现 图 A.5 所 示 的 界面 ， 我 们 可 以 在 该 界面 中 选择 虚拟 机 。 选 择 完 毕 后 点 击 下 一 步 。 

















& Oracle VM VirtualBox 管理 器 
$ dv, me 
新 建 (N) 设置 (S) 清除 启动 (T) 
A Lud EG 
加 $i 要 导出 的 虚拟 电脑 | 
| 
请 选择 要 导出 的 虚拟 电脑 。 可 以 选择 多 个 虚拟 电脑 。 务 必 注 意 先 关 
闭 这 些 虚 拟 电 脑 。 
> 





专家 模式 返回 取消 





> 声音 


主机 音频 驱动 : CoreAudio 
控制 芯片 ; ICH AC97 


a 网 络 
, 网卡 1: Intel PRO/1000 MT 桌面 (网 络 地 址 转换 (NAT)) 








(9 USB 设 备 
USB 控制 器 : OHCI, EHCI 
| | RAMA: O (0 活动) 














图 A.5 导出 虚拟 电脑 ( 1 ) 
接 下 来 选择 导出 到 的 位 置 ， 再 点 击 下 一 步 开 始 导 出 。 
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5060 Oracle VM VirtualBox 管理 器 


Ir ` 
— v» o | 
存储 设置 
| ] 
"i 
请 选择 要 导出 OVFJOVA 的 文件 名 。 
“如果 您 使 用 OVA 文件 扩展 名 ， 那 么 所 有 文件 都 将 合并 为 一 个 “开放 
(O0 式 虚 拟 化 格式 包 ”。 
如 果 您 使 用 OVF 扩展 名 ， 将 分 成 若干 独立 的 文件 。 
不 允许 其 他 扩展 名 。 E 
a 





























(N) RES) 清除 启动 (T) 
文件 : /Users/bpbook/Documents/my_ubuntu.ova ] A 











格式 : OVF10 O B 
| — E A Manifest 文件 





" E: mx 


主机 音频 驱动 : CoreAudio 
1 控制 芯片 : ICH AC97 


2 网 络 
网 卡 1 Intel PRO/1000 MT 桌面 (网 络 地 址 转换 (NAT)) 














( i$ usBig& 


USB 控制 器 : OHCI, EHCI 
| 设备 疑 选 : 。 0 (0 活动) 











A.6 导出 虚拟 电脑 ( 2 ) 


这 样 ， 我 们 就 完成 了 虚拟 电脑 的 导出 (图 A.6 )。 

FAIR HE, KRKE “VirtualBox > 管理 > 导入 虚拟 电脑 ”， 选 择 之 前 导出 的 ova 
文件 进行 导入 ， 我 们 就 又 能 使 用 该 设置 下 的 虚拟 机 了。VirtulBox HU EL I RE., BEP 
来 ,在 附录 B 中 ， 我 们 将 学 习 如 何在 新 建 的 虚拟 机 镜像 中 安装 OS ( Ubuntu )。 


附录 B OS (Ubuntu) 的 设置 


我 们 在 附录 A 中 已 经 准备 好 了 环境 ， 现 在 来 了 解 一 下 安 狠 客 OS( Ubuntu ) 的 流程 。 





B.1 安装 Ubuntu 


首先 从 下 述 URL FR Ubuntu 的 CD 镜像 (网 B.1 )。Ubuntu 为 多 种 执行 环境 准备 了 相应 的 
镜像 ， 本 书 使 用 的 是 Server 版 。 








http://www.ubuntu.com/download/server 











Ubuntu | Community Ask! Developer Design Discourse Hardware Insights Juju Partners Shop More ~ 


U b un tu® Cloud Server Desktop Phone Tablet TV EDE THIS Download 





Download > Server > ARM POWER8 


Download Ubuntu Server 


Ubuntu Server 14.04.1 LTS 


The Long Term Support version of Ubuntu Server, including the Icehouse 
release of OpenStack and support guaranteed until April 2019 — 64 bit only. 


Download 
Recommended for most users. 


Ubuntu Server 14.04.1 LTS release notes & Alternative downloads and torrents » 





B.1 下 载 Ubuntu 


这 里 我 们 使 用 的 版 本 是 ubuntu-14.04.1-server-amd64.iso。 下 载 完 成 之 后 局 动 之 前 创建 好 的 虚 
拟 机 。 初 次 启动 时 会 显示 如 图 B.2 所 示 的 安装 媒体 选择 界面 。 

这 里 选择 刚刚 下 载 的 CD 镜像 并 继续 。 之 后 界面 上 会 显示 启动 按钮 ， 点 击 按 钮 实际 启动 OS 
即 可 O 
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请 选择 一 个 虚拟 光盘 文件 或 已 放 入 光 
盘 的 光驱 来 启动 虚拟 电脑 。 


此 光盘 应 可 启动 并 且 有 你 想 安 装 的 操 
作 系 统 。 下 次 关闭 虚拟 电脑 时 ， 此 光 
盘 可 自动 弹出 ; 你 也 可 以 手动 弹出 。 


人 


ubuntu-14.04.1-server-an ~ 








Qj c) m) d Là M I i 19 v) Zr 36 


图 B.2 VirtualBox 初次 启动 窗口 








装 包 启动 后 ， 进 行 Ubuntu 的 安装 设置 。 


Amharic Francais MakeaoHckMa Tamil 
Arabic Gaeilge Halayalam STOM 
Asturianu Galego Marathi Thai 
benapyckas | Gujarati Burmese Tagalog 
bbArapcku n" Nepali Türkce 
Bengali Hindi Nederlands Uyghur 
Tibetan Hrvatski Norsk bokmål YKpaiHCbka 
Bosanski Magyar Norsk nynorsk Tiéng viêt 
Català BahasaIndonesia | Punjabi (Gurmukhi) rhe ej 48) 
Čeština Íslenska Polski 中 文 (繁体 ) 
Dansk Italiano Portugués do Brasil 
Deutsch 日 本 语 Portugues 
Dzongkha jobo3mo Romána 
EAAnUvLKO Kazak Pyccknň 

Khmer samegillii 
Esperanto 8336 5 oN 
Español z0] Slovenčina 
Eesti Kurdî Slovenščina 
Euskara Lao Shgip 
3l ws Lietuviškai Cpncku 
Suomi Latviski Svenska 





GJ 9&9 g - Wi usi) (s s 


图 B.3 Ubuntu 的 安装 界面 


首先 是 语言 设置 ， 最 开始 请 选择 English 并 按 Enter EE (fk B.3), 一 开始 选择 中 文 会 导致 在 
VirtualBox 上 运行 的 控制 台 显 示 乱 码 ， 所 以 语言 问题 等 到 后 面 再 作 调 整 。 

















附录 B OS (Ubuntu) 的 设置 


ubuntu? 


Install Ubuntu Server 





à €. um s) s zs 


B.4 Ubuntu 的 安装 准备 


设置 完 语 言 之 后 选择 Install Ubuntu Server 进入 下 一 步 (图 B.4 )。 


[!!] Select a language 


Choose the language to be used for the installation process. The selected language will 
also be the default language for the installed system. 


Language: 


C 

Albanian 
Arabic 
Asturian 
Basque 
Belarusian 
Bosnian 
Bulgarian 
Catalan 
Chinese (Simplified) 
Chinese (Traditional) 
Croatian 
Czech 
Danish 
Dutch 
English 
Esperanto 
Estonian 
Finnish 
French 
Galician 
German 
Greek 


el 


No localization 
Shqip 

us 
Asturianu 
Euskara 
benapyckas 
Bosanski 
Bbnrapcku 
Català 
中 文 (简体 ) 
max GER) 
Hrvatski 
Cest ina 
Dansk 
Neder lands 
English 
Esperanto 
Eesti 
Suomi 
Français 
Galego 
Deutsch 
EAANV LK 
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«G0 Back» 


«Tab» moves; «Space» selects; «Enter» activates buttons 





0 ou. i)d vs 


B.5 Ubuntu Select a language 


如 图 B.6 ~ 图 B.8 所 示 ， 安 竣 开 始 后 ， 系 统 将 询问 “选择 当前 所 在 地 ”和 “键盘 设置 "， 各 
位 请 根据 目 己 的 情况 进行 设置 。 
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[!!] Select your location 


The selected location will be used to set your time zone and also for example to help 
select the system locale. Normally this should be the country where uou live. 


Listed are locations for: Asia. Use the «Go Back» option to select a different continent 
or region if your location is not listed. 


Country, territory or area: 


«Go Back» 


<Tab> moves; 《Space> selects; 


Afghanistan 
Bahrain 
Bangladesh 

Bhutan 

Brunei Darussalam 
Cambodia 


Urin a) 


Hong Kong 

India 

Indonesia 

Iran, Islamic Republic of 
Irag 

Israel 

Japan 

Jordan 

Kazakhstan 

Korea, Democratic People's Republic of 
Korea, Republic of 

Kuwait 

Kyrgyzstan 


<Enter> activates buttons 





Bmoegsumaeidszs 


B.6 Ubuntu Select your location 


[1] Configure locales 


There is no locale defined for the combination of language and country you have selected. 
You can now select your preference from the locales available for the selected language. 
The locale that will be used is listed in the second column. 


Countru to base default 


«Ba Back» 


«F1» for help; «Tab» moves; 


locale settings on: 


Antigua and Barbuda 
Rustralia 
Botswana 
Canada 

Hong Kong 
India 

Ireland 

Neu Zealand 
Nigeria 
Philippines 
Singapore 
South Africa 
United Kingdom 
United States 
zambia 
zimbabwe 


«Space» selects; «Enter» activates buttons 





B.7 Ubuntu Configure locales 
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[ Configure the keyboard 


The layout of keyboards varies per country, with some countries having multiple common 
layouts. Please select the country of origin for the keyboard of this computer. 


Country of origin for the keyboard: 


Armenian 
Azerbaijani 
Bambara 

Bangla 

Belarusian 
Belgian 

Bosnian 

Braille 

Bulgarian 

Burmese 

Chinese WW WT 
Croatian 

Czech 

Danish 

Dhivehi 

Dutch 

Dzongkha 

English (Cameroon) 
English (Ghana) 
English (Nigeria) 
English (South Africa) 
English (UK) 
English (US) 


«Go Back» 


«Tab» moves; «Space» selects; «Enter» activates buttons 





Qo.9umiu d gis-:s 


B.8 Ubuntu Configure the keyboard 


设置 完成 后 ， 安 装 就 会 正式 开始 。 接 下 来 会 显示 网 络 的 设置 。 如 图 B. 所 示 输 入 Hostname 
并 进入 下 一 步 。 


[1] Configure the network 
Please enter the hostname for this system. 
The hostname is a single word that identifies your system to the network. If you don't 
knou what uour hostname should be, consult uour network administrator. If uou are setting 
up your oun home network, you can make something up here. 
Hostname: 


bpbook-ubuntu 


«Go Back» «Cont inue» 


«Tab» moves; «Space» selects; «Enter» activates buttons 





G cou 5 dei) zs 


B.9 Ubuntu Configure the network 





根据 安装 进度 ， 接 下 来 会 进入 创建 账户 的 界面 ， 这 里 要 设置 “用 户 名 ”和 “密码 ”。 这 里 我 
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们 设置 一 个 名 为 bpbook 的 用 户 (图 B.10 )。 


[!!] Set up users and passwords 


A user account will be created for you to use instead of the root account for 
non-administrative activities. 


Please enter the real name of this user. This information will be used for instance as 
default origin for emails sent by this user as well as any program which displays or uses 
the user's real name. Your full name is a reasonable choice. 


Full name for the neu user: 


«GO Back» «cont inue» 





«Tab» moves; «Space» selects; «Enter» activates buttons 


Gg osg:umiuiddit)zs 


B.10 Ubuntu Set up users and passwords 


接 下 来 是 时 区 的 设置 ， 系 统 会 自动 为 我 们 推测 当前 时 区 。 确 认 无 误 后 点 击 Yes( 图 B.11 )。 





[!] Configure the clock 
Based on your present physical location, your time zone is Asia/Harbin. 
If this is not correct, you may select from a full list of time zones instead. 


Is this time zone correct? 


«G0 Back» «No» 





<Tab> moves; «Space» selects; «Enter» activates buttons 


g osug.-desi)*:2 s 


B.11 Ubuntu Configure the clock 


然后 是 便 盘 分 区 的 设置 。 选 择 Guided - use entire disk and set up LVM 并 继续 (图 B.12 )。 
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[! Partition disks 


The installer can guide you through partitioning a disk (using different standard 
schemes) or, if you prefer, you can do it manually. Hith guided partitioning you will 
still have a chance later to review and customise the results. 


If uou choose guided partitioning for an entire disk, you will next be asked which disk 
should be used. 


Partitioning method: 


Guided - use entire disk 

Guided - use entire disk and set up LYM 

Guided - use entire disk and set up encrypted LVM 
Manual 


«G0 Back» 


«Tab» moves; «Space» selects; «Enter» activates buttons 





B.12 Ubuntu Partition disks ( 1 ) 


随后 的 分 区 设置 会 询问 Write the changes to disk and configure LYM， 这 里 选择 Yes (KI 
B.13 )。 随 后 还 会 出 现 几 次 询问 ， 基 本 上 都 选 Yes 就 可 以 了 。 


[1!] Partition disks 


Before the Logical Volume Manager can be configured, the current partitioning scheme has 
to be written to disk. These changes cannot be undone. 


After the Logical Volume Manager is configured, no additional changes to the partitioning 
scheme of disks containing physical volumes are allowed during the installation. Please 
decide if you are satisfied with the current partitioning scheme before continuing. 


The partition tables of the following devices are changed: 
SCSI3 (0,0,0) (sda) 


Write the changes to disks and configure LVM? 


<Tab> moves; “Space> selects; 《Enter> activates buttons 





gossggumia d OOE 


B.13 Ubuntu Partition disks ( 2 ) 


如 果 是 网 络 连接 受 限 的 环境 ， 建 议 设 置 HTTP 代理 以 保证 程序 包 管 理 器 可 以 访问 网 络 。 不 
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受 限 制 的 情况 下 则 可 以 直接 选择 Continue 继续 安装 ( 图 B.14 ). 


[!] Configure the package manager 


If uou need to use a HTTP proxy to access the outside world, enter the proxy information 
here. Otherwise, leave this blank. 


The proxy information should be given in the standard form of 
"http://L[I[user] [:pass] @] host [:port] /". 


HTTP proxy information (blank for none): 


«Go Back» «Cont inue» 


«Tab» moves; «Space» selects; «Enter» activates buttons 





Gg o9. gs:zs 


B.14 Ubuntu Configure the package manager 


与 安全 更 新 相关 的 问题 要 选择 Install security updates automatically ( 图 B.15 ) OS 开发 每 天 
都 在 进行 ， 其 中 包括 很 多 重要 的 安全 更 新 ， 因 此 我 们 需要 选择 这 个 选项 ， 以 保证 OS 能 持续 安 
ESCORE 


[1] Configuring tasksel 
Applying updates on a frequent basis is an important part of keeping your system secure. 


Bu default, updates need to be applied manuallu using package management tools. 
Alternatively, you can choose to have this system automatically download and install 
security updates, or you can choose to manage this system over the web as part of a group 
of systems using Canonical's Landscape service. 


Hou do you want to manage upgrades on this system? 
No automatic up 


Install securit 
Manage sustem with Landscape 





«Tab» moves; «Space» selects; «Enter» activates buttons 


ge. qs 


B.15 Ubuntu Configuring tasksel 
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ÀJ 


由 于 Ubuntu Server 版 是 精简 安装 ， 所 以 这 个 阶段 并 没有 安装 任何 软件 。 这 里 我 们 只 色 选 
OpenSSH server 并 继续 ( 图 B.16 )。 选 择 由 空格 键 完成 。 





[!] Software selection 


At the moment, only the core of the system is installed. To tune the system to your 
needs, you can choose to install one or more of the following predefined collections of 
software. 


Choose software to install: 


«cont inue» 





«Tab» moves; «Space» selects; «Enter» activates buttons 


B.16 Ubuntu Software Selection 


问 是 否 安装 GRUB 引导 加 载 程 序 ， 这 里 选择 Yes 并 继续 (图 B.17 )。 


[!] Install the GRUB boot loader on a hard disk 


It seems that this neu installation is the onlu operating sustem on this computer. If so, 
it should be safe to install the GRUB boot loader to the master boot record of your first 
hard drive. 


Warning: If the installer failed to detect another operating system that is present on 
your computer, modifying the master boot record will make that operating system 


temporarilu unbootable, though GRUB can be manuallu configured later to boot it. 


Install the GRUB boot loader to the master boot record? 


«GO Back» «NO» 


«Tab» moves; «Space» selects; «Enter» activates buttons 





G o9 mi): 


B.17 Ubuntu Install the GRUB boot loader on a hard disk 
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之 后 只 要 等 安装 进度 条 走 完 ， 我 们 就 完成 客 OS 的 安装 了 了 。 安 装 完毕 之 后 会 
以 我 们 这 里 立刻 重新 启动 (图 B.18 )。 








[!!] Finish the installation 


Installation complete 
Installation is complete, so it is time to boot into your neu system. Make sure to remove 
the installation media (CD-ROM, floppies), so that you boot into the neu system rather 
than restarting the installation. 


«G0 Back» 


«Tab» moves; «Space» selects; «Enter» activates buttons 





B.18 Ubuntu Finish the installation 











74 OS 重启 后 将 显示 如 图 B.19 所 示 的 登录 界面 。 用 前 面 创建 的 用 户 登 录 即 可 。 


Ubuntu 14.04.1 LTS bpbook-ubuntu tty1 


bpbook-ubuntu login: bpbook 





CEA F Amii d OOE 


B.19 Ubuntu 的 登录 界面 
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B.2 SSH 的 设置 





ee ee ee wpe 
了 OpenSSH server， 因 此 不 必 再 另行 安装 后。 现在 在 客 OS 的 控制 台 执 行 下 述 命令 ， 检 查 ssh 
块 是 否 已 经 启动 (LIST 1 )。 





© LIST 1 查看 进程 


$ ps aux | grep sshd 





如 果 进 程 列 表 中 有 /usr/sbin/sshd -D ， 就 表示 SSH 守护 进程 已 经 启动 。 


NOTE 
如 果 前 面 忘记 安装 OpenSSH server， 则 需要 通过 apt-get 等 命令 手动 安装 。 


$ sudo apt-get install ssh 


现在 SSH EZAK, TUME OS 通过 SSH 登录 客 OS T., VirtualBox 提供 了 多 种 连 
接 方法 ， 这 里 我 们 用 NAT 连 接 的 端口 转发 机 制 ， 将 主 OS 的 2222 端口 与 客 0S 的 SSH 端口 


(22 ) 连接 起 来 。 
从 VirtualBox 管理 界面 选择 “设置 > 网 络 > 网 卡 1> 端 口 转发 "， 然 后 如 图 B.20 进行 设置 。 


Oracle VM VirtualBox 管理 器 


my. ubuntu - 网 络 


g ww m m 


存储 声音 网 络 端口 ”共享 文件 夹 用 户 界面 


m qb 


= H 


T: 


协议 主机 IP 主机 端口 子 系统 IP 子 系统 端口 € 
Rule 1 TCP 2222 22 C 





E 


Cancel OK 
ee 
控制 芯片 : ICH AC97 | 


(SmRE | | 
网 卡 1: Intel PRO/1000 MT 桌面 (网 络 地 址 转换 (NAT)) | 


























B.20 VirtualBox 端口 转发 的 设置 
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如 图 B.20 设置 完毕 后 ， 在 主 OS 的 控制 台 上 输入 LIST 2 所 示 的 命令 。 


E LIST2 SSH 连接 


$ ssh -p 2222 sacok@l27.0.0.1 

DhecaurhentrcuituobrhostoUbo 0x91] 2222 [327 0 0.1] :2222)" can't 0e estabirSshecd- 
RSA key tingerprimece LS CO:e8s 9T s 96:86:24 s 06l 96 sles 0D: 518 pb 7158197 8 10g T0, 

Are you sure you want to continue connecting (yes/no)? yes 

Warning: Permanently added '[127.0.0.1]:2222' (RSA) to the list of known hosts. 


bpbooke127.0.0.1's password: 


NOTE 
这 里 假定 主 OS 为 OS X， 因 此 使 用 的 是 ssh 命令 。 而 Windows 没有 ssh 命令， 因此 需要 
使 用 其 他 软件 ( 例如 PuTTY? ) 进行 SSH 连接 。 


@ 前 的 bpbook 是 安装 Ubuntu 时 创建 的 用 户 名 ， 各 位 请 替换 成 自己 的 用 户 名 。 初 次 连接 时 
系统 会 询问 Are you sure you want to continue connecting (yes/mo)?， 这 里 输入 yes。 随 后 系统 还 会 
要 求 输 入 密码 ， 此 时 输入 创建 用 户 时 设置 的 密码 即 可 。 顺 利 登 录 客 OS 后 将 显示 图 B.21 所 示 的 
内 容 。 


Welcome to Ubuntu 14.04.1 LTS (GNU/Linux 3.13.0-32-generic x86 64) 
x Documentation: https: //help.ubuntu.com/ 


System information as of Mon Nov 10 19:22:09 JST 2014 


System load: 0.02 Processes: 73 
Usage of /: 14.9% of 6.99GB Users logged in: e 
Memory usage: 10% IP address for eth0: 10.0.2.15 


Swap usage: 0% 


Graph this data and manage this system at: 
https: //landscape.canonical.com/ 


74 packages can be updated. 
38 updates are security updates. 


Last login: Mon Nov 10 19:22:09 2014 
bpbookebpbook-ubuntu:-$ B 


B.21 Æ OS 通过 SSH 连接 客 OS 


NOTE 

一 般 说 来 ， 通 过 SSH 连接 服务 器 时 只 校 验 密码 并 不 安全 。 本 节 内 容 面 向 的 是 个 人 开发 环境 
的 搭建 ， 因 此 只 讲 了 用 密码 登陆 服务 器 的 方法 。 要 想 搭建 更 加 安全 的 环境 ， 建 议 使 用 “ 公 钥 加 
WAAZV XtfTAXUEo 


(D nttp://www.chiark.greenend.org.uk/-sgtatham/putty/ 
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AIA https://zh.wikipedia.org/wiki/$E52859ACZE5$BC£80$E5ZAF286$2 


E9$929$A5SE5$8ASAOSE5SAF£86 


B3 ”中文 的 设置 


B LIST 3 ”安装 中 文 语言 包 
sudo apt-get install language-pack-zh-hans 
sudo update-locale LANG=zZh CN .UTF-8 


执行 LIST 3 中 的 命令 后 即 可 安装 中 文 的 locale 文件 并 完成 设置 。 安 装 完成 之 后 在 login- 
shell 的 设置 文件 ( .bashrc ) 中 设置 下 述 环 境 变 量 ( LIST 4 )。 


© LIST4 在 .bashrc 中 设置 用 于 设 定语 言 的 环境 变量 


export LANG-"zh CN.UTE-8" 
export LANGUAGE-"zh CN:zh" 


设置 完成 之 后 ， 用 source 命令 反映 设置 (LIST35S )。 


© LIST5 反映 .bashrc 的 设置 


$ source -/.bashrc 





到 这 里 ， 中 文 就 设置 完毕 了 。 以 后 再 启动 支持 中 文 的 Vim 等 程序 时 ， 可 以 看 到 信息 都 是 以 
中 文 显示 的 。 


B.4 添加 用 户 











用 于 开发 的 服务 器 上 党 要 运行 许多 应 用 ,但 从 安全 角度 讲 ， 最 好 不 要 用 root 用 户 来 运行 
Eiis 

所 以 ， 我 们 需要 根据 应 用 的 开发 进度 ， 设 置 能 够 通过 sudo 命令 修改 服务 硕 和 中 间 件 设置 
的 组 以 及 用 户 。 这 里 我 们 以 添加 dev 组 和 bpuser 用 户 为 例 进行 学 习 。 

首先 用 bpbook 用 户 登 录 并 创建 组 。 如 LIST 6 所 示 ， 以 root 权限 执行 grzoupadd 命令 来 创 
建 dev 组 。 
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E LIST6 添加 组 


$ sudo groupadd dev 





接 下 来 创建 用 户 。 用 adduser 命令 创建 bpuser 用 户 。 此 时 用 --ingroup 选项 指定 dev 可 以 
让 新 用 户 加 入 dev £H C LIST 7 )。 


B LIST7 添加 用 户 


$ sudo adduser bpuser --ingroup dev 


这 样 一 来 就 创建 了 bpuser 用 户 。 需 要 删除 用 户 时 使 用 userdel 命令 进行 删除 (LIST 8 )。 





ƏB LIST 8 删除 用 户 


$ sudo userdel -r bpuser 


Ubuntu 14.04 默认 有 sudo 组 ， 被 添加 到 这 个 组 的 用 户 均 可 以 使 用 sudo 命令 。 


回 LIST9 向 组 添加 用 户 
$ sudo usermod -aG sudo bpuser 
不 过 在 目前 的 设置 下 ，dev 组 的 用 户 每 次 使 用 sudo 命令 都 要 输 一 遍 密 码 ， 这 必然 影响 开发 
环境 的 便捷 性 。 因 此 我 们 要 让 dev 组 的 用 户 在 执行 sudo 命令 时 人 免 去 输入 密码 的 麻烦 。 
我 们 在 /etc/sudoers.d/ 目录 下 创建 一 个 文件 ， 并 给 dev 组 设置 权限 。 先 执行 下 述 visudo fm 
今 ( LIST 10 )。 


© LIST 10 执行 visudo 


$ sudo visudo -f /etc/sudoers.d/dev 


NOTE 


对 sudo 进行 个 别 设置 时 ， 尽 量 不 要 编辑 原 设 置 文件 /etc/sudoers， 最 好 是 如 上 所 述 在 /etc/ 
sudoers.d/ 下 放置 设置 文件 。 因 为 在 升级 OS SERA ZG RUD AR ER d /etc/sudoers 文件 ， 导 致 所 
有 账户 都 无 法 使 用 sudo 命令 。 这 样 做 可 以 免除 上 述 顾 虑 。 


执行 visudo 命令 后 会 生成 /etc/sudoers.d/dev 文件 。 对 该 文件 作 如 下 描述 


E LIST 11 sudo 设置 示例 
sdev ALL=(ALL) NOPASSWD:ALL 
按照 LIST 11 所 示 设 置 之 后 ，dev 组 的 所 有 用 户 就 都 可 以 不 输入 密码 直接 执行 sudo fi 


^T. 
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NOTE 
本 三 ， 我 们 站 在 本 地 开发 环境 的 角度 ， 学 习 了 如 何 设置 无 需 密码 执行 sudo 命令 ， 以 维持 
开发 环境 的 便捷 性 。 


但 是 ，sudo 命令 可 以 使 用 root 权限 对 服务 器 进行 操作 ,一旦 用 户 被 窃取 ， 融 来 的 损害 将 
会 非 弟 大 。 这 个 风险 我 们 一 定 要 清楚 。 

因此 ， 如 果 我 们 使 用 的 是 可 通过 互联 网 访问 的 共享 服务 器 、 正 式 运 营 的 服务 器 ， 那 么 当 我 
们 考虑 设置 “无 需 密码 执行 sudo 命令 ”时 ， 一 定 要 慎之 又 慎 。 
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